changelog Published on 2026-11-21

xfmpress v0.4.15: build-time KaTeX math and Mermaid diagram plugins

8 min read # xfmpress# changelog

v0.4.15 turns two high-frequency content capabilities — math and diagrams — into official plugins, and quietly fixes two subtle bugs in the plugin pipeline. If you write technical posts or documentation, this one is worth a close look.

What this release solves

The usual approach to formulas and diagrams is dropping KaTeX or Mermaid JS into the browser and letting it render at runtime: the raw source flashes on first paint, and every page carries a CDN dependency. xfm-plugin-math moves rendering to build time. xfm-plugin-mermaid keeps drawing in the browser (Mermaid inherently needs JS) but restricts the script to pages that actually contain a diagram.

What changed

Added

  • xfm-plugin-math — KaTeX rendering at build time. Inline $a^2$, display $$…$$ and the LaTeX \(…\) / \[…\] forms all work. Formulas are swapped for private-use placeholders before Markdown runs, so the underscore in $a_1$ no longer turns into emphasis, and code blocks plus \$ escapes are left alone. Pages get plain KaTeX HTML, with the stylesheet and woff2 fonts copied into assets/katex/ — no client-side JS, no CDN.
  • xfm-plugin-mermaid — fenced mermaid blocks become <pre class="mermaid"> and are drawn in the browser. The renderer is injected only on pages that contain a diagram, served locally from assets/mermaid/ (or from a CDN with mermaid.mode: 'cdn'), and can be disabled per page with mermaid: false.
  • Both plugins ship with READMEs, tests (test/run.js) and a demo post on the example site.
  • Example-site demos for 0.4.14 — examples/blog now exercises every feature from the previous release: a projects custom collection (in the nav, kept out of the post stream), a Chinese/English about translation pair with localized nav labels and hreflang, an authors.json data file consumed by a site-local plugins/author-byline.js plugin that injects bylines into posts, and a feature post whose list-card summary is the automatic excerpt. The example changelog page is synced through 0.4.14.

Fixed

  • Later afterBuild plugins could not see earlier plugin output. site.extraFiles was only filled after the whole hook ran, so xfm-plugin-deadlinks reported assets generated by other plugins (e.g. assets/katex/katex.min.css) as dead links. Outputs are now accumulated during the hook, in plugin order.
  • Collection items leaked into RSS / JSON Feed. Both feed plugins read site.documents rather than the post stream, so collection entries marked as independent still appeared in feed.xml / feed.json. Non-posts collections now mark their items rss: false (respecting an explicit front-matter rss value), which the feed plugins already honor.

Should you upgrade

Both plugins are optional installs; sites that don't use them are unaffected, and the fixes carry no breaking changes. One thing worth noting: if you run the deadlinks plugin alongside math, the false dead-link reports disappear after upgrading — that's a correction, not a regression. For syntax details, see the Markdown guide.

Comments