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 (dynamic map size, starts at 32MB).
• 🔌 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

🛠️ 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.