MkDocs KaTeX SSR Plugin

A MkDocs plugin that renders LaTeX math on the server side using KaTeX, offering faster load times, layout stability, and optional offline support.

Note

Maintenance Philosophy: This project is self-maintained. I welcome bug reports and corrections, but please note that I may not have the bandwidth to accept significant feature requests or major functional additions. Pull requests for bug fixes are appreciated.

This project's code and documentation were generated by Antigravity (Google DeepMind) and verified by the maintainer.

✨ Highlights

Traditional client-side rendering relies on JavaScript in the browser to convert LaTeX strings into HTML. This can lead to Layout Shift and slower performance. MkDocs KaTeX SSR pre-renders all math during the mkdocs build process using a local persistent process. The resulting HTML contains ready-to-view markup.

• 🚀 Ultra High Performance: Employs an advanced batch-IPC processing architecture for mathematical formulas, deeply decoupling Python and JavaScript serialization and lowering rendering overhead by up to $O(1)$ IPC calls per page.
• ⚡ Native Bun Support: Automatically detects and leverages the revolutionary Bun runtime for faster startup and plugin execution. Seamlessly falls back to Node.js when Bun is unavailable.
• 📦 Smart Dependency Management: Auto-installs KaTeX dependencies via npm or bun add during the first run if they are missing locally.
• 🗃️ Built-in LMDB Cache: Recompilation is instantaneous thanks to the integrated ultra-fast LMDB engine (4GB limit by default).
• 🔌 Offline Mode (Self-Contained): Safely enables the "Offline Mode" which pulls CSS, fonts, and scripts directly to your local site bundle.
• 🔄 Client-Side Fallback: Introduces a flexible disable option to revert to traditional client-side rendering while preserving asset management benefits.

📦 Installation

Prerequisites

• Bun or Node.js: Must be installed and available in your system PATH (bun is recommended for optimal speed).
• Python: 3.8+

Install Plugin

uv add mkdocs-katex-ssr
# or traditional pip
pip install mkdocs-katex-ssr

⚙️ Configuration

Add the plugin to your mkdocs.yml:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

plugins:
  - katex-ssr:
      # --- Basic Configuration ---
      use_bun: auto # Auto-detects Bun for improved compilation speed. Can be explicitly forced to true/false.
      verbose: true # Enable build logs for each page detailing cache hits.
      disable: false # Set to true to switch to client-side rendering only
      add_katex_css: true # Required (true by default)
      katex_css_filename: "katex-swap.min.css"
      
      # --- Script Loading ---
      ssr_contribs:
        - mhchem # Loaded in the renderer for SSR
        
      client_scripts:
        - copy-tex # Injected as <script> tag for the browser
      
      # --- KaTeX Options ---
      katex_options:
        macros:
          "\\RR": "\\mathbb{R}"

Client-Side Only Mode (disable: true)

If you prefer to use KaTeX's traditional "Auto-render" extension instead of Server-Side Rendering (SSR), set disable: true.

Important

When disable: true, add_katex_css must be true. If add_katex_css is set to false, the plugin will return a configuration error.

Offline Mode (Self-Contained)

Enable embed_assets to host all KaTeX files locally within your site.

plugins:
  - katex-ssr:
      embed_assets: true

🎛️ Configuration Options

Option	Type	Default	Description
use_bun	bool/str	'auto'	Instructs the plugin to use the bun runtime for speed enhancements. Can be true, false, or 'auto'.
disable	bool	false	If true, skips SSR and uses client-side "Auto-render".
verbose	bool	false	Logs formula counts and processing time per page.
katex_dist	str	CDN URL	Base path for KaTeX (URL or local path).
add_katex_css	bool	true	Whether to inject the CSS link tag. Must be true if disable is true.
katex_css_filename	str	katex.min.css	The CSS filename to load.
embed_assets	bool	false	Copies assets to output dir for offline support.
ssr_contribs	list	[]	KaTeX contribs for SSR (or client if disable: true).
client_scripts	list	[]	KaTeX contribs always injected for the browser.
katex_options	dict	{}	Options passed to KaTeX (including macros).

🛠️ Troubleshooting

• Validation Error: If you see "When 'disable' is true, 'add_katex_css' must also be true", ensure you haven't set add_katex_css: false while disabling SSR.
• Runtime Error: Verify node or bun is installed and registered in your environment PATH.

📄 License

MIT License.

---

Generated by Antigravity (Google DeepMind) and verified manually by the maintainer.