mkdocs-katex-ssr 1.0.2

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 without spawning a new process for every item.
• Offline Support: Optional "Offline Mode" copies all necessary CSS, fonts, and scripts to your site directory, removing external CDN dependencies.
• Smart Asset Management: Separate configuration for server-side processing scripts (like mhchem) and client-side interactive scripts (like copy-tex).
• Clean Output: Aggressive warning suppression for a quieter build log.

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 ---
      katex_dist: "https://cdn.jsdelivr.net/npm/katex@latest/dist/"
      add_katex_css: true
      katex_css_filename: "katex-swap.min.css" # Use swap version for better font-display behavior
      
      # --- Script Loading ---
      # Scripts needed for rendering (Server-Side). e.g., chemical formulas.
      # These are NOT sent to the browser.
      ssr_contribs:
        - mhchem
        
      # Scripts needed for interaction (Client-Side). e.g., clipboard copy.
      # These ARE injected into the HTML.
      client_scripts:
        - copy-tex
      
      # --- KaTeX Options ---
      katex_options:
        macros:
          "\\RR": "\\mathbb{R}"

Offline Mode (Self-Contained)

If you need your documentation to work without an internet connection (or just want to host everything yourself), enable embed_assets.

plugins:
  - katex-ssr:
      embed_assets: true
      # You can specify a local path if auto-detection fails
      # katex_dist: "./node_modules/katex/dist/"

What this does:

1. Copies Files: It copies katex.min.css (or your chosen filename), the fonts/ directory, and any specified client_scripts from your local node_modules to site/assets/katex.
2. Relative Linking: It updates all HTML citations to point to these local files using correct relative paths (e.g., ../assets/katex/katex.min.css).

Advanced Configuration Options

Option	Type	Default	Description
katex_dist	str	jsDelivr	Base URL for CDN, or local file path to KaTeX distribution.
add_katex_css	bool	true	Whether to inject the CSS link tag.
katex_css_filename	str	katex.min.css	The specific CSS file to load. katex-swap.min.css is recommended.
embed_assets	bool	false	If true, copies assets to output dir and links locally.
ssr_contribs	list	[]	List of KaTeX contrib libraries to load in the Node.js renderer (e.g., mhchem).
client_scripts	list	[]	List of KaTeX contrib libraries to load in the browser (e.g., copy-tex).
copy_assets_to	str	assets/katex	Destination directory for copied assets (relative to site_dir).
katex_options	dict	{}	Standard options passed to katex.renderToString (macros, etc.).

Troubleshooting

• katex module not found: Ensure npm install katex (or pnpm/yarn) has been run in your project root, or specific the path via katex_dist.
• Node.js error: The plugin requires node to be in your PATH. On Windows, ensure you can run node --version in your terminal.

License

This project is licensed under the MIT License.