Vaulthalla Logo

Configuration

The public config model has three top-level namespaces:

1payloadMarkdown({2  code: {},3  themes: {},4  config: {},5  collections: {6    posts: {7      code: {},8      themes: {},9      config: {},10    },11  },12})

Use each namespace for one job:

  • code controls code fence and Shiki rendering.
  • themes registers named directive themes.
  • config controls Markdown wrapper and typography presentation.

Full Example

1import { DEFAULT_CODE_LANGS, payloadMarkdown } from '@valkyrianlabs/payload-markdown'2 3payloadMarkdown({4  code: {5    enhanced: true,6    fullBleed: false,7    langs: [...DEFAULT_CODE_LANGS, 'latex', 'r'],8    lineNumbers: true,9    shikiTheme: 'github-dark',10  },11  collections: {12    pages: true,13    posts: {14      code: {15        lineNumbers: false,16      },17      config: {18        className: '[&_li::marker]:text-cyan-200/90',19      },20      themes: {21        card: {22          extendDefaults: true,23          items: [24            {25              name: 'postHeroCard',26              classes: 'rounded-2xl border border-white/[0.06] bg-cyan-950/15 p-5',27            },28          ],29        },30      },31    },32  },33  config: {34    size: 'lg',35    variant: 'blog',36  },37  themes: {38    card: {39      extendDefaults: true,40      items: [41        {42          name: 'forge',43          classes: 'rounded-2xl border border-white/[0.06] bg-cyan-950/15 p-5',44        },45      ],46    },47  },48})

code

1payloadMarkdown({2  code: {3    enhanced: true,4    fullBleed: false,5    langs: [...DEFAULT_CODE_LANGS, 'latex', 'r'],6    lineNumbers: true,7    shikiTheme: 'github-dark',8  },9})

Options:

  • enhanced
  • fullBleed
  • langs
  • lineNumbers
  • shikiTheme

Use shikiTheme, not theme, to avoid confusion with directive themes.

themes

1payloadMarkdown({2  themes: {3    card: {4      extendDefaults: true,5      items: [6        {7          name: 'cyan',8          classes: 'rounded-2xl border border-white/[0.06] bg-cyan-950/15 p-5',9        },10      ],11    },12  },13})

Theme objects use classes, not className. extendDefaults defaults to true, so custom themes are added to the built-in set unless you opt out.

config

1payloadMarkdown({2  config: {3    className: '[&_li::marker]:text-cyan-200/90',4    enableGutter: true,5    mutedHeadings: true,6    size: 'lg',7    variant: 'blog',8    wrapperClassName: 'max-w-4xl',9  },10})

config is for Markdown wrapper presentation. It is not the code block API and it is not the directive theme registry.

Collection Overrides

1payloadMarkdown({2  code: {3    lineNumbers: true,4  },5  collections: {6    posts: {7      code: {8        lineNumbers: false,9      },10      config: {11        variant: 'docs',12      },13      themes: {14        toc: {15          items: [16            {17              name: 'postSidebar',18              classes: 'rounded-xl border border-white/[0.06] bg-[#18191c] px-4 py-3',19            },20          ],21        },22      },23    },24  },25})

Collection config overrides plugin-level config for that collection.

Deprecated Aliases

These still work but are no longer preferred:

  • config.options.langs → code.langs
  • config.options.lineNumbers → code.lineNumbers
  • config.options.theme → code.shikiTheme
  • config.options.enhancedCodeBlocks → code.enhanced
  • config.fullBleedCode → code.fullBleed
  • config.sectionClassName → directive themes
  • config.columnClassName → directive themes

New code values win over legacy config.options.