zfb

Type to search...

to open search from anywhere

v0.1.0-next.12

v0.1.0-next.12

Released: 2026-05-28

[Md Extras] Opt-in Markdown features catalog

This release ships the complete [Md Extras] epic: 14 opt-in Markdown features, the zfb-md-extras and zfb-md-ast crates, a revised Core pipeline, and the Markdown Features docs category.

Migration required — 4 features moved from Core to Opt-in

The following four features were previously always-on. They are now opt-in. If your site relied on them, add the corresponding keys to zfb.config.ts:

import { defineConfig } from "zfb/config";

export default defineConfig({
  markdown: {
    features: {
      imageEnlarge: true,        // was always-on in Core
      mermaid: true,             // was always-on in Core
      admonitionsPreset: true,   // was always-on in Core (6 built-in admonition names)
      headingMarkerToc: true,    // was always-on in Core
    },
  },
});

All four accept true (use defaults) or a config object for option overrides. Omitting a key means the feature is off and no extra bytes are emitted.

New infrastructure

  • zfb-md-ast crate — shared MdastNode, HastNode, MdastVisitor, and HastVisitor types. Both Core (zfb-content) and Opt-in (zfb-md-extras) features implement these traits from a single source.
  • zfb-md-extras crate — all 14 opt-in features, gated by MarkdownConfig.features at runtime.
  • Pipeline::with_defaults_and_features — the new primary pipeline constructor; accepts a MarkdownFeatures config struct and appends only the visitors whose flags are set.
  • BuildContext — passed to opt-in features that need project-level context (source map, content root, site URL) at visit time.
  • Typed attribute schemas (from #584) — DirectiveRegistry now accepts typed attribute schemas; unknown attributes or type mismatches emit a build-time warning.
  • Test infrastructure — zfb-test-utils and a dedicated test harness for zfb-md-extras; cross-feature integration tests in Wave 7 (#582).

14 new Opt-in features

Enable any combination via markdown.features.* in zfb.config.ts.

  • admonitionsPreset — the six built-in admonition directive types (note, tip, warning, danger, info, details). Doc: Admonitions preset.
  • mermaid — render Mermaid flowcharts from fenced code blocks at build time. Doc: Mermaid diagrams.
  • imageEnlarge — wrap block-level images in an enlargeable figure with a zoom button. Doc: Image enlarge.
  • headingMarkerToc — auto-insert a <ul>/<li> TOC after a designated heading. Options: heading, maxDepth. Doc: Heading-marker TOC.
  • githubAlerts — render > [!NOTE] / > [!TIP] / > [!WARNING] / > [!IMPORTANT] / > [!CAUTION] blockquotes as styled JSX components. Doc: GitHub alerts.
  • readingTime — compute estimated reading time and inject it into the compiled frontmatter. Doc: Reading time.
  • githubAutolinks — automatically link GitHub issue/PR/commit references (#123, org/repo#456, abc1234). Options: repo. Doc: GitHub autolinks.
  • codeEnrichment — diff markers (// [!code ++] / // [!code --]) and per-line highlighting ({1,3-5} in fence info). Options: diffMarkers, lineHighlight. Doc: Code-block enrichment.
  • codeTabs — group consecutive fenced code blocks into a tabbed switcher. Doc: Code tabs.
  • ruby — render {漢字|かんじ} syntax as HTML <ruby> elements. Doc: Ruby annotation.
  • tocExport — export a structured heading tree into the compiled JSX module for framework-side TOC rendering. Doc: TOC export.
  • imageDimensions — inject width and height attributes on <img> elements from the actual source file at build time. Doc: Image dimensions.
  • linkValidation — treat broken internal links as hard build errors (configurable). Doc: Link validation.
  • transclude — inline the content of another file using the :::include directive, with cycle detection and depth limiting. Options: maxDepth. Doc: Transclusion.

Math

Math support (TeX / LaTeX) is documented as a recipe: embed raw TeX in a fenced code block tagged math and render it client-side with KaTeX or MathJax. This keeps math off the server-rendered critical path and avoids shipping a TeX parser into the binary for the minority of sites that need it.

Cross-feature integration tests (#582)

Wave 7 sibling issue #582 added cross-feature integration tests covering interactions between Opt-in features (e.g. githubAlerts + admonitionsPreset, transclude + headingMarkerToc, codeEnrichment after SyntectPlugin). These tests live in crates/zfb-md-extras/tests/.

Caller migration landed (#586)

The build, dev, and snapshot pipelines now thread markdown.features end-to-end through a single feature-aware entry point (Pipeline::with_defaults_and_full_config). This is what makes the opt-in behavior above actually take effect:

  • A default zfb.config.ts with no features key builds with the four former-Core framework features (mermaid, imageEnlarge, admonitionsPreset, headingMarkerToc) off.
  • Setting e.g. features: { mermaid: true } now emits the mermaid wrapper; features: { mermaid: false } (or omitting it) does not.
  • zfb build, zfb dev, and the content-collection snapshot walker all share the same dispatch, so the JSX content_hash stays byte-identical across the build and snapshot surfaces.

The legacy Pipeline::with_defaults* constructors are retained unchanged for backwards-compatible direct (library / test) callers.

Docs

  • New Markdown Features sidebar category with one page per feature.
  • 8 Core feature pages documenting always-on plugins.
  • Customizing Markdown slimmed down to a pipeline overview with a pointer to the new category.
  • Extending the Markdown Pipeline updated with Core-vs-Opt-in guidance and complete visitor ordering rules.
  • Design Philosophy — new section on the opt-in extras catalog and the three-consumer threshold for future additions.
  • Engine vs Framework — notes that framework-flavored Markdown features ship as opt-in extras.

Revision History