Markdown Features

Every feature zfb's Markdown pipeline provides — Core (always-on) and Opt-in (enabled via zfb.config.ts).

zfb's Markdown pipeline is layered. A set of Core features runs unconditionally for every content collection, giving you heading anchors, server-side syntax highlighting, CJK-friendly emphasis, and more. On top of that, a catalog of Opt-in features can be enabled one-by-one in zfb.config.ts under markdown.features.*.

This page is the map. Each feature has its own page with a usage example, config key, and ordering notes.

Dependency graph

zfb-content          — Core features live here; always compiled in
  └─ zfb-md-extras   — Opt-in features; compiled in but gated at runtime
       └─ zfb-md-ast — Shared AST types (MdastNode, HastNode, visitors)

The zfb-md-ast crate defines the MdastVisitor and HastVisitor traits and the shared node types. Both Core and Opt-in features implement these traits.

Tier convention

• Core — active in every build. No config key. Lives in zfb-content.

• Opt-in — inactive by default. Enable via markdown.features.* in zfb.config.ts. Lives in zfb-md-extras.

Each feature page shows a Core or Opt-in badge near its title.

Enabling Opt-in features

import { defineConfig } from "zfb/config";

export default defineConfig({
  markdown: {
    features: {
      mermaid: true,
      directives: {
        note: "Note",
        tip: "Tip",
      },
    },
  },
});

Pass true (use defaults) or a config object (override specific options). Omitting a key means the feature is off; no extra bytes are emitted.

Core features

These always-on plugins ship as part of zfb-content's default pipeline.

• CJK-friendly emphasis — re-tokenises bold/italic adjacent to CJK ideographs and kana.

• Heading links — slugified id attributes and self-referencing anchor links on every heading.

• Code block title — renders a filename label above a fenced code block from title="…".

• External links — adds target and rel attributes to outbound links (configurable).

• Resolve links — rewrites internal link targets using the content source map.

• Strip .md extension — removes .md/.mdx suffixes from internal link hrefs.

• Syntax highlighting — server-side highlighting via syntect; always on, theme-configurable.

• Directives registry — maps :::name/::name/:name directive syntax to JSX components.

Opt-in features

Enable each in markdown.features.*. All live in zfb-md-extras.

• Directives — register :::name / ::name / :name directive syntax that maps to your own JSX components (zero defaults — you supply the vocabulary).

• Mermaid diagrams — renders Mermaid flowcharts from fenced code blocks.

• Heading-marker TOC — auto-inserts a table of contents after a designated heading.

• GitHub alerts — renders > [!NOTE] / > [!WARNING] blockquotes as styled components.

• Reading time — computes estimated reading time and injects it into frontmatter.

• GitHub autolinks — links GitHub issue/PR/commit references (#123, org/repo#456, abc1234) automatically.

• Code-block enrichment — adds diff markers and per-line highlighting to fenced code blocks.

• Code tabs — groups consecutive fenced code blocks into a tabbed switcher.

• Ruby annotation — renders {これは}^{これ} (caret, primary) or {漢字|かんじ} (pipe, legacy alias) syntax as HTML <ruby> elements.

• TOC export — exports a structured heading tree into the compiled JSX module for framework-side rendering.

• Image dimensions — injects width and height attributes on <img> elements from the actual file.

• Link validation — warns on broken internal links by default; hard build errors with failOnBroken: true.

• Transclusion — inlines the content of another file using the :::include directive.

See also

• Design Philosophy — the three-consumer threshold for promoting a recipe to an Opt-in feature.

• Extending the Markdown Pipeline — write a Rust visitor and wire it into the engine.

• Custom Directives — register new directive names without writing Rust.

• Recipe: Enlargeable Images — userland replacement for the removed imageEnlarge built-in, using the img component override.

• Recipe: Admonitions — register :::note, :::tip, etc. via directives with component stubs and CSS hooks.