mkdocs-katex-ssr 0.1.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

mkdocs_katex_ssr/plugin.py

@@ -150,7 +150,7 @@ class KatexSsrPlugin(BasePlugin):
                 
                 result = json.loads(response_line.decode('utf-8'))
                 if result.get('status') == 'success':
-                    return result.get('html')
+                    return '<div class="arithmatex">{html}</div>'.format(html=result.get('html'))
                 else:
                     print(f"KaTeX error: {result.get('message')}")
             except Exception as e:

mkdocs_katex_ssr-1.0.2.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: mkdocs-katex-ssr
+Version: 1.0.2
+Summary: A MkDocs plugin for server-side rendering of KaTeX math.
+Author-email: RainPPR <2125773894@qq.com>
+License-Expression: MIT
+Project-URL: Homepage, https://raineblog.dpdns.org/mkdocs-katex-ssr/
+Project-URL: Documentation, https://raineblog.dpdns.org/mkdocs-katex-ssr/configuration/
+Project-URL: Repository, https://github.com/raineblog/mkdocs-katex-ssr
+Project-URL: Issues, https://github.com/raineblog/mkdocs-katex-ssr/issues
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.1.0
+Requires-Dist: beautifulsoup4>=4.9.0
+Dynamic: license-file
+
+# 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`).
+- **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 ---
+      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 |
+| :--- | :--- | :--- | :--- |
+| `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.

mkdocs_katex_ssr-1.0.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+mkdocs_katex_ssr/plugin.py,sha256=hfbYOK9Fz0hR-OXut-VpgNJ-InJMwpNrwMvTg3-kJpo,11125
+mkdocs_katex_ssr/renderer.js,sha256=15lIck7GXZHiAza9IpnSbu9HmeklaDp_zubetQQowkU,1967
+mkdocs_katex_ssr-1.0.2.dist-info/licenses/LICENSE,sha256=Bea4m1bAyMhuJT5bCGl76QfpKatJarfMzl9vcrdXRgQ,1064
+mkdocs_katex_ssr-1.0.2.dist-info/METADATA,sha256=6FA_aL4s8tLEbECU0yVFEody4hcv5gG_Y0c6ZHpp8Nc,5398
+mkdocs_katex_ssr-1.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mkdocs_katex_ssr-1.0.2.dist-info/entry_points.txt,sha256=l3PrOPi_1AqGLse2BTZVz2SB8rn3I4NRVI-wDUbIHVg,68
+mkdocs_katex_ssr-1.0.2.dist-info/top_level.txt,sha256=FdfQyPUx4r9kgiqTW4da0TPUdBbOda_0PXjVkfGmsgs,17
+mkdocs_katex_ssr-1.0.2.dist-info/RECORD,,

mkdocs_katex_ssr-0.1.0.dist-info/METADATA

@@ -1,10 +0,0 @@
-Metadata-Version: 2.4
-Name: mkdocs-katex-ssr
-Version: 0.1.0
-Summary: A MkDocs plugin for server-side rendering of KaTeX math.
-Author-email: Your Name <your.email@example.com>
-License: MIT
-License-File: LICENSE
-Requires-Dist: mkdocs>=1.1.0
-Requires-Dist: beautifulsoup4>=4.9.0
-Dynamic: license-file

mkdocs_katex_ssr-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-mkdocs_katex_ssr/plugin.py,sha256=9HcxJv4Q1SfWMmnNvWwpw0oaJCuCFCrbhBM5WMgp4vc,11073
-mkdocs_katex_ssr/renderer.js,sha256=15lIck7GXZHiAza9IpnSbu9HmeklaDp_zubetQQowkU,1967
-mkdocs_katex_ssr-0.1.0.dist-info/licenses/LICENSE,sha256=Bea4m1bAyMhuJT5bCGl76QfpKatJarfMzl9vcrdXRgQ,1064
-mkdocs_katex_ssr-0.1.0.dist-info/METADATA,sha256=UHxjskpQ8Zb0smgBOE0dIOeWvlojZkQ3BlQ0Sz8OS0Q,298
-mkdocs_katex_ssr-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-mkdocs_katex_ssr-0.1.0.dist-info/entry_points.txt,sha256=l3PrOPi_1AqGLse2BTZVz2SB8rn3I4NRVI-wDUbIHVg,68
-mkdocs_katex_ssr-0.1.0.dist-info/top_level.txt,sha256=FdfQyPUx4r9kgiqTW4da0TPUdBbOda_0PXjVkfGmsgs,17
-mkdocs_katex_ssr-0.1.0.dist-info/RECORD,,