# 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.*

## ✨ 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 SQLite Cache**: Recompilation is instantaneous thanks to the integrated `.cache` engine.
- **🔌 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

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

```yaml
plugins:
  - katex-ssr:
      embed_assets: true
```

## 🎛️ Configuration Options

| Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `use_bun` | bool/str | `'auto'` | Instructs the plugin to use the `bun` runtime for speed enhancements. Can be `true`, `false`, or `'auto'`. |
| `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.
- **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.*
