# 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 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`).
- **Performance Monitoring**: Detailed build-time logging for each page tracking formula counts, cache hits, and processing speeds.
- **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

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

```yaml
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 |
| :--- | :--- | :--- | :--- |
| `verbose` | bool | `false` | If true, logs the number of formulas, cache hits, and time spent processing each page. |
| `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.
