API Reference

Package Exports

Main export:

1import {2  DEFAULT_CALLOUT_THEMES,3  DEFAULT_CARD_THEMES,4  DEFAULT_CARDS_THEMES,5  DEFAULT_CELL_THEMES,6  DEFAULT_CODE_LANGS,7  DEFAULT_COLUMNS_THEMES,8  DEFAULT_DETAILS_THEMES,9  DEFAULT_SECTION_THEMES,10  DEFAULT_STEPS_THEMES,11  DEFAULT_TAB_THEMES,12  DEFAULT_TABS_THEMES,13  DEFAULT_TOC_THEMES,14  MarkdownBlock,15  markdownField,16  payloadMarkdown,17} from 'payload-markdown'

Server export:

1import {2  MarkdownBlockComponent,3  MarkdownRenderer,4  PayloadMarkdownField,5} from 'payload-markdown/server'

Client export ('use client' components for bundled apps):

1import {2  MarkdownRendererClient,3  PayloadMarkdownField,4} from 'payload-markdown/client'

PayloadMarkdownField is the same component as the server export's PayloadMarkdownField. Fields created by markdownField() use the admin component path <package>/server#PayloadMarkdownField, where <package> is the name you installed (payload-markdown or @valkyrianlabs/payload-markdown), so existing import maps for the scoped package do not change; <package>/client#PayloadMarkdownField resolves to the same component. MarkdownRendererClient adds tab and code-copy behavior to HTML rendered with renderMarkdown(): render it with containerId set to the id of the element that contains the HTML.

MCP export (server-only, for @payloadcms/plugin-mcp and custom agents):

1import {2  getMarkdownGuide,3  MarkdownAgentError,4  payloadMarkdownMcpPrompts,5  payloadMarkdownMcpTools,6  publishMarkdown,7  readMarkdownDocuments,8  validateMarkdown,9  withPayloadMarkdownMcp,10  writeMarkdown,11} from 'payload-markdown/mcp'

See AI Agents and MCP, the MCP tools reference and Custom Agents.

The server and client exports require a bundler (they import CSS and React client code). The main, render and advanced exports load in plain Node.

Headless render export (no React, Next.js or CSS; works in plain Node):

1import {2  compileMarkdown,3  createHeadingSlugger,4  extractHeadingAnchors,5  getDirectiveSpec,6  readPayloadMarkdownSettings,7  renderMarkdown,8  slugifyHeading,9} from 'payload-markdown/render'

Directive spec (generated from the directive registry at build time; the same data getDirectiveSpec() returns):

1import spec from 'payload-markdown/directive-spec.json' with { type: 'json' }

The spec lists every directive (kind, open and close markers, [label] attribute), its attributes with a type (url, enum, string, boolean or number), allowed values and theme group, the built-in theme names, badge types and targets, tab-value and heading-slug rules, and parser constraints. specVersion changes only when the JSON shape changes.

Stylesheet export:

1import 'payload-markdown/styles.css'

Advanced export:

1import {2  createHeadingSlugger,3  createPayloadMarkdownIconRegistryEntry,4  createPayloadMarkdownIconRegistrySource,5  extractHeadingAnchors,6  slugifyHeading,7  vlMdCodeBlockConfig,8  vlMdConfig,9  vlMdTailwindField,10} from 'payload-markdown/advanced'

renderMarkdown

1function renderMarkdown(markdown: string, config?: RenderMarkdownConfig): Promise<RenderedMarkdown>2 3type RenderMarkdownConfig = MarkdownRenderConfig & {4  collectionSlug?: string5  scope?: 'blocks' | 'field'6  // settings object, Payload config or Payload instance; false: no plugin defaults7  settings?: PayloadMarkdownSettingsSource | false | null8}9 10type RenderedMarkdown = {11  diagnostics: RenderDiagnostic[]12  errors: string[]13  headings: Array<{ depth: number; id: string; text: string }>14  html: string15  links: Array<{ kind: 'definition' | 'directive' | 'image' | 'link'; url: string }>16  text: string17  warnings: string[]18}19 20type RenderDiagnostic = {21  code?: string22  column?: number23  line?: number24  message: string25  severity: 'error' | 'info' | 'warning'26  source: 'code' | 'directive' | 'icon' | 'render' | 'theme'27}

Like MarkdownRenderer, renderMarkdown applies the plugin defaults for scope (default field) and collectionSlug from settings, or from the process-wide settings registry when settings is omitted. readPayloadMarkdownSettings(source) returns the settings stored on a Payload config or instance.

links lists authored URLs before sanitization; unsafe directive links are removed from html and reported in diagnostics.

PayloadMarkdownConfig

1type PayloadMarkdownConfig = {2  code?: MarkdownCodeConfig3  collections?: Partial<Record<CollectionSlug, PayloadMarkdownCollectionConfig | true>>4  config?: ConfigOptions5  enabled?: boolean6  icons?: PayloadMarkdownIconsConfig7  themes?: MarkdownDirectiveThemes8}

enabled defaults to enabled behavior. Set enabled: false only when you want the plugin to return the incoming Payload config unchanged.

PayloadMarkdownIconsConfig

1type PayloadMarkdownIconPack = {2  alias: string3  path: string4}5 6type PayloadMarkdownIconsConfig = {7  baseDir: string8  packs: PayloadMarkdownIconPack[]9}

Icon refs in Markdown use @pack/name, such as @fa-duotone/home. The plugin validates pack aliases, pack paths, icon refs, traversal attempts, unknown packs, and missing SVG files.

PayloadMarkdownCollectionConfig

1type PayloadMarkdownCollectionConfig = {2  code?: MarkdownCodeConfig3  config?: ConfigOptions4  field?: Omit<MarkdownFieldOptions, 'name'>5  fieldName?: string6  installField?: boolean7  installIntoBlocks?: boolean8  themes?: MarkdownDirectiveThemes9}

MarkdownCodeConfig

1type MarkdownCodeConfig = {2  enhanced?: boolean3  fullBleed?: boolean4  langs?: string[]5  lineNumbers?: boolean6  shikiTheme?: string7}

Defaults:

• enhanced: true
• lineNumbers: true when enhanced rendering is enabled
• shikiTheme: github-dark
• fullBleed: false

MarkdownConfig

1type MarkdownConfig = {2  className?: string3  enableGutter?: boolean4  lead?: ReactNode5  mutedHeadings?: boolean6  size?: 'lg' | 'md' | 'sm'7  variant?: 'blog' | 'compact' | 'docs' | 'unstyled'8  wrapperClassName?: string9 10  // Deprecated aliases11  columnClassName?: string12  fullBleedCode?: boolean13  options?: RenderMarkdownOptions14  sectionClassName?: string15}

MarkdownRenderConfig

1type MarkdownRenderConfig = {2  code?: MarkdownCodeConfig3  icons?: PayloadMarkdownIconsConfig4  themes?: MarkdownDirectiveThemes5} & MarkdownConfig

ConfigOptions

config can be shared or split by field and block scope:

1type ConfigOptions =2  | MarkdownConfig3  | {4      blocks?: MarkdownConfig5      field?: MarkdownConfig6    }

Renderer Props

1type MarkdownRendererProps = {2  as?: keyof JSX.IntrinsicElements3  collectionSlug?: string4  emptyFallback?: ReactNode5  errorFallback?: ReactNode6  markdown?: null | string7  scope?: 'blocks' | 'field'8  settings?: PayloadMarkdownSettingsSource | false | null9} & MarkdownRenderConfig

Markdown Field Options

1type MarkdownFieldOptions = {2  admin?: Partial<TextField['admin']>3  defaultValue?: string4  label?: string5  localized?: boolean6  name?: string7  required?: boolean8}

Directive Names

Layout directives:

• section
• 2col
• 3col
• cell

Static directives:

• badge
• badges
• button
• buttons
• callout
• details
• toc
• steps
• cards
• card
• tabs
• tab

Close markers:

• :::
• :::end
• :::endcol
• :::endsection

Directive Theme Groups

1type MarkdownDirectiveThemes = {2  callout?: MarkdownDirectiveThemeGroup3  card?: MarkdownDirectiveThemeGroup4  cards?: MarkdownDirectiveThemeGroup5  cell?: MarkdownDirectiveThemeGroup6  columns?: MarkdownDirectiveThemeGroup7  details?: MarkdownDirectiveThemeGroup8  section?: MarkdownDirectiveThemeGroup9  steps?: MarkdownDirectiveThemeGroup10  tab?: MarkdownDirectiveThemeGroup11  tabs?: MarkdownDirectiveThemeGroup12  toc?: MarkdownDirectiveThemeGroup13}

Theme items use classes:

1type MarkdownDirectiveTheme = {2  classes: string3  label?: string4  name: string5}

Default Theme Names

Callout:

• soft
• solid
• glass

Card:

• default
• muted
• glass
• cyan
• violet
• emerald
• amber
• danger

Cards:

• default
• compact
• spacious
• feature-grid

Steps:

• default
• muted
• glass
• cyan

Tabs:

• default
• muted
• glass
• underline
• pills

Tab:

• default
• muted
• glass

Details:

• default
• muted
• glass

TOC:

• default
• compact
• sidebar

Section:

• default
• muted
• panel

Columns:

• default
• panel

Cell:

• default
• panel