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](https://katex.org/), 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

```bash
pip install mkdocs-katex-ssr
```

## Configuration

Add the plugin to your `mkdocs.yml`:

```yaml
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.

```yaml
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.