Code Blocks

Fenced code blocks are rendered with Shiki during the Markdown compile pipeline. The browser receives finished HTML and does not need a client-side syntax highlighter.

Preferred Code Config

Use the top-level code namespace:

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})

Use collection-level code when one collection needs different behavior:

1payloadMarkdown({2  code: {3    lineNumbers: true,4  },5  collections: {6    posts: {7      code: {8        langs: [...DEFAULT_CODE_LANGS, 'latex'],9        lineNumbers: false,10      },11    },12  },13})

Options

• enhanced: applies the plugin's normalized code block renderer, defaulting to true
• fullBleed: lets fenced code blocks extend beyond the normal content width on larger screens
• langs: replaces or extends the Shiki language list
• lineNumbers: controls visible line numbers when enhanced rendering is enabled
• shikiTheme: selects the Shiki theme, defaulting to github-dark

shikiTheme is intentionally separate from directive themes.

Default Languages

DEFAULT_CODE_LANGS includes:

1cpp, java, js, ts, jsx, tsx, json, python, rust, html, css, yaml, sql

Extend it when authors need additional Shiki languages:

1import { DEFAULT_CODE_LANGS, payloadMarkdown } from '@valkyrianlabs/payload-markdown'2 3payloadMarkdown({4  code: {5    langs: [...DEFAULT_CODE_LANGS, 'go', 'php', 'vue'],6  },7})

If a fence uses an unknown language, the renderer falls back to plain text highlighting instead of failing the page.

Language Fences

Use standard fenced code blocks with a language identifier:

1```ts2export function sum(a: number, b: number) {3  return a + b4}5```

The language hint is passed to Shiki during Markdown compilation.

Enhanced Rendering

Enhanced rendering provides:

• Shiki tokenization
• normalized spacing and layout
• optional line numbers
• empty-line normalization
• copy button behavior from the renderer client helper
• server-rendered HTML output

Disable it when you want output closer to raw Shiki:

1payloadMarkdown({2  code: {3    enhanced: false,4  },5})

When enhanced is false, line numbers are disabled even if lineNumbers is true.

Full-Bleed Code

Use fullBleed when long code examples should visually break out from normal prose width:

1payloadMarkdown({2  code: {3    fullBleed: true,4  },5})

Renderer-level overrides use the same namespace:

1<MarkdownRenderer2  code={{ fullBleed: true }}3  markdown={content}4/>

Legacy Aliases

The old config.options shape still works:

1payloadMarkdown({2  config: {3    fullBleedCode: true,4    options: {5      enhancedCodeBlocks: true,6      langs: [...DEFAULT_CODE_LANGS],7      lineNumbers: true,8      theme: 'github-dark',9    },10  },11})

Prefer:

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