mkdocs-katex-ssr 1.0.8

A MkDocs plugin for server-side rendering of KaTeX math.

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.

Why Server-Side Rendering (SSR)?

Traditional client-side rendering relies on JavaScript in the browser to convert LaTeX strings (e.g., $\sqrt{a^2 + b^2}$) into HTML. This can lead to:

• Layout Shift: Content jumps as math loads.
• Slower Performance: The browser must download and parse the KaTeX library before rendering.
• Dependency: Requires client-side JavaScript execution.

MkDocs KaTeX SSR pre-renders all math during the mkdocs build process using a local Node.js process. The resulting HTML contains ready-to-view markup.

Features

• High Performance: Uses a persistent Node.js process to render equations efficiently.
• Offline Support: Optional "Offline Mode" copies all necessary CSS, fonts, and scripts to your site directory.
• Hybrid Script Management: Separate configuration for server-side processing (e.g., mhchem) and client-side interaction (e.g., copy-tex).
• Flexible Rendering: New disable option to switch back to traditional client-side rendering while keeping asset management benefits.
• Built-in Cache: Includes a SQLite-based cache to speed up recompilation.

Installation

Prerequisites

• Node.js: Must be installed and available in your system PATH.
• Python: 3.8+

Install Plugin

pip install mkdocs-katex-ssr

Configuration

Add the plugin to your mkdocs.yml:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

plugins:
  - katex-ssr:
      # --- Basic Configuration ---
      verbose: true # Enable build logs for each page
      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 Node.js 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.

Why use this?

• Faster builds (skips SSR logic).
• Compatibility with certain client-side plugins that expect raw LaTeX in the DOM.
• Shared configuration: Automatically passes macros, ssr_contribs, and client_scripts to the client-side renderer.

[!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
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.
• Node.js issues: Verify node is in your PATH.

License

MIT License.