mkdocs-katex-ssr 0.1.0__tar.gz → 1.0.3__tar.gz

mkdocs_katex_ssr-1.0.3/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: mkdocs-katex-ssr
+Version: 1.0.3
+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-0.1.0 → mkdocs_katex_ssr-1.0.3}/mkdocs_katex_ssr/plugin.py

@@ -167,7 +167,7 @@ class KatexSsrPlugin(BasePlugin):
         soup = BeautifulSoup(output, 'html.parser')
         math_elements = soup.find_all(class_='arithmatex')
         for el in math_elements:
-            content = el.get_text().strip()
+            content = el.get_text(strip=True)
             display_mode = False
             
             if content.startswith('\\(') and content.endswith('\\)'):
@@ -184,9 +184,10 @@ class KatexSsrPlugin(BasePlugin):
                 latex = content
             
             rendered_html = self._render_latex(latex, display_mode)
-            if rendered_html:
-                new_soup = BeautifulSoup(rendered_html, 'html.parser')
-                el.replace_with(new_soup)
+            new_soup = BeautifulSoup(rendered_html, 'html.parser')
+
+            el.clear()
+            el.append(new_soup)
 
         # Assets Injection
         css_file = self.config['katex_css_filename']

mkdocs_katex_ssr-1.0.3/mkdocs_katex_ssr.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: mkdocs-katex-ssr
+Version: 1.0.3
+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-0.1.0 → mkdocs_katex_ssr-1.0.3}/pyproject.toml

@@ -4,17 +4,25 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mkdocs-katex-ssr"
-version = "0.1.0"
+version = "1.0.3"
 description = "A MkDocs plugin for server-side rendering of KaTeX math."
+readme = "README.md"
 authors = [
-    {name = "Your Name", email = "your.email@example.com"}
+    {name = "RainPPR", email = "2125773894@qq.com"}
 ]
-license = {text = "MIT"}
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
 dependencies = [
     "mkdocs>=1.1.0",
     "beautifulsoup4>=4.9.0",
 ]
 
+[project.urls]
+Homepage = "https://raineblog.dpdns.org/mkdocs-katex-ssr/"
+Documentation = "https://raineblog.dpdns.org/mkdocs-katex-ssr/configuration/"
+Repository = "https://github.com/raineblog/mkdocs-katex-ssr"
+Issues = "https://github.com/raineblog/mkdocs-katex-ssr/issues"
+
 [project.entry-points."mkdocs.plugins"]
 katex-ssr = "mkdocs_katex_ssr.plugin:KatexSsrPlugin"
 

mkdocs_katex_ssr-0.1.0/PKG-INFO

@@ -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/mkdocs_katex_ssr.egg-info/PKG-INFO

@@ -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