Syntax highlighting

Server-side syntax highlighting via syntect — always on, theme-configurable.

SyntectPlugin runs server-side syntax highlighting at build time. It is always active. Every fenced code block in your Markdown is highlighted via syntect — a Rust library using Sublime Text–compatible grammars — and the colour-annotated HTML is baked into the output. No JavaScript is shipped to the browser for highlighting.

Theme configuration

The default theme is "base16-ocean.dark". Change it in zfb.config.ts:

export default {
  codeHighlight: {
    theme: "Solarized (light)",
  },
};

Custom .tmTheme files and supplementary client-side patterns are covered in the dedicated guide below.

Dual light/dark themes

Instead of a single theme, set both themeLight and themeDark to highlight every block twice and emit per-token CSS custom properties, so the active colour can be chosen by the page's light/dark mode at render time — no JavaScript:

export default {
  codeHighlight: {
    themeLight: "InspiredGitHub",
    themeDark: "base16-ocean.dark",
  },
};

themeLight and themeDark must be set together, and they are mutually exclusive with theme. The <pre> carries class="syntect-dual" and the consumer resolves the colours with a single light-dark() CSS rule. These are syntect theme names, not Shiki names. See the dedicated guide for the emitted markup and the CSS rule.

Output modes

There are three ways to colour tokens, selected by codeHighlight.mode and the theme fields:

• Single-theme inline (default) — mode: "inline" with one theme; per-token colours baked into style="color:…". Self-contained HTML.

• Dual-theme inline — themeLight + themeDark (still mode: "inline"); per-token --shiki-light / --shiki-dark custom properties resolved by a light-dark() CSS rule.

• Class mode (recommended) — mode: "class"; each token gets a semantic role class (hi-kw, …) coloured through re-themeable --zfb-hi-* custom properties, with no baked-in colours. See the guide's Class mode section.

mode is mutually exclusive with the theme fields: mode: "class" alongside any of theme / themeLight / themeDark / themesDir is a build error.

Full documentation

For theme names, custom .tmTheme loading, class-mode role tokens, client-side supplementary highlighting, and post-build custom grammar patterns, see Syntax Highlighting.

Ordering note

SyntectPlugin runs last in the hast phase, after CodeTitlePlugin, MermaidPlugin, and all other code-block visitors. It replaces each <pre><code> element with a raw HTML fragment; any plugin that needs to read the structured <pre> must run before it.