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 '@valkyrianlabs/payload-markdown'

Server export:

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

Advanced export:

1import {2  createPayloadMarkdownIconRegistryEntry,3  createPayloadMarkdownIconRegistrySource,4  vlMdCodeBlockConfig,5  vlMdConfig,6  vlMdTailwindField,7} from '@valkyrianlabs/payload-markdown/advanced'

PayloadMarkdownConfig

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

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}

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} & 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:

• 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