mkdocs-katex-ssr 0.1.0__tar.gz

mkdocs_katex_ssr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RainPPR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_katex_ssr-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+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/README.md

@@ -0,0 +1,110 @@
+# 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/plugin.py

@@ -0,0 +1,272 @@
+import os
+import json
+import subprocess
+import threading
+import warnings
+import logging
+import requests
+import shutil
+from mkdocs.plugins import BasePlugin
+from mkdocs.config import config_options
+from mkdocs.utils import get_relative_url
+from bs4 import BeautifulSoup
+
+# Extremely aggressive global warning suppression
+warnings.filterwarnings("ignore")
+os.environ["PYTHONWARNINGS"] = "ignore"
+
+class WarningFilter(logging.Filter):
+    def filter(self, record):
+        msg = record.getMessage().lower()
+        if "pkg_resources" in msg or "jieba" in msg or "deprecationwarning" in msg or "userwarning" in msg:
+            return False
+        return True
+
+# Apply filter to all potential loggers
+for logger_name in ["mkdocs", "mkdocs.plugins", "py.warnings", ""]:
+    logger = logging.getLogger(logger_name)
+    logger.addFilter(WarningFilter())
+
+logging.captureWarnings(True)
+
+class KatexSsrPlugin(BasePlugin):
+    config_scheme = (
+        ('katex_dist', config_options.Type(str, default='https://cdn.jsdelivr.net/npm/katex@latest/dist/')),
+        ('katex_css_filename', config_options.Type(str, default='katex.min.css')),
+        ('add_katex_css', config_options.Type(bool, default=True)),
+        ('embed_assets', config_options.Type(bool, default=False)),
+        ('copy_assets_to', config_options.Type(str, default='assets/katex')),
+        ('ssr_contribs', config_options.Type(list, default=[])),
+        ('client_scripts', config_options.Type(list, default=[])),
+        # Legacy/Alias for ssr_contribs to maintain some compat, though behavior changes
+        ('contrib_scripts', config_options.Type(list, default=[])), 
+        ('katex_options', config_options.Type(dict, default={})),
+    )
+
+    def __init__(self):
+        self.process = None
+        self.lock = threading.Lock()
+        self._asset_cache = {}
+        self._local_dist_path = None
+
+    def _ensure_trailing_slash(self, path):
+        if not path.endswith('/') and not path.endswith('\\'):
+            return path + '/'
+        return path
+
+    def _resolve_url(self, base, path):
+        base = base.replace('\\', '/')
+        if base.startswith('http'):
+            return base.rstrip('/') + '/' + path.lstrip('/')
+        else:
+            return os.path.normpath(os.path.join(base, path))
+
+    def on_config(self, config):
+        self.config['katex_dist'] = self._ensure_trailing_slash(self.config['katex_dist'])
+        
+        project_dir = os.path.dirname(config['config_file_path'])
+        
+        # Merge legacy contrib_scripts into ssr_contribs if used
+        if self.config['contrib_scripts']:
+            # Append unique items
+            for script in self.config['contrib_scripts']:
+                if script not in self.config['ssr_contribs']:
+                    self.config['ssr_contribs'].append(script)
+
+        # Asset resolution logic
+        possible_dist = self._resolve_url(project_dir, self.config['katex_dist'])
+        if os.path.isdir(possible_dist):
+             self._local_dist_path = possible_dist
+        else:
+             node_modules = os.path.join(project_dir, 'node_modules')
+             dist = os.path.join(node_modules, 'katex', 'dist')
+             if os.path.isdir(dist):
+                 self._local_dist_path = dist
+
+        # Start Node.js process
+        renderer_path = os.path.join(os.path.dirname(__file__), 'renderer.js')
+        
+        use_shell = os.name == 'nt'
+        cmd = ['node', renderer_path]
+        if use_shell:
+             cmd = f'node "{renderer_path}"'
+        
+        try:
+            env = os.environ.copy()
+            node_modules = os.path.join(project_dir, 'node_modules')
+            if 'NODE_PATH' in env:
+                env['NODE_PATH'] = node_modules + os.pathsep + env['NODE_PATH']
+            else:
+                env['NODE_PATH'] = node_modules
+
+            self.process = subprocess.Popen(
+                cmd,
+                cwd=project_dir,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                shell=use_shell,
+                env=env
+            )
+            
+            # Send ONLY ssr_contribs to Node
+            node_contribs = [c for c in self.config['ssr_contribs'] if '://' not in c]
+            setup_payload = {
+                'type': 'setup',
+                'contribs': node_contribs
+            }
+            try:
+                line = (json.dumps(setup_payload) + '\n').encode('utf-8')
+                self.process.stdin.write(line)
+                self.process.stdin.flush()
+            except Exception as e:
+                print(f"Error during KaTeX setup: {e}")
+            
+        except Exception as e:
+            print(f"Error starting KaTeX renderer: {e}")
+            self.process = None
+        
+        return config
+
+    def _render_latex(self, latex, display_mode=False):
+        if not self.process:
+            return None
+        
+        with self.lock:
+            payload = {
+                'type': 'render',
+                'latex': latex,
+                'displayMode': display_mode,
+                'options': self.config['katex_options']
+            }
+            try:
+                line = (json.dumps(payload) + '\n').encode('utf-8')
+                self.process.stdin.write(line)
+                self.process.stdin.flush()
+                
+                response_line = self.process.stdout.readline()
+                if not response_line:
+                    return None
+                
+                result = json.loads(response_line.decode('utf-8'))
+                if result.get('status') == 'success':
+                    return result.get('html')
+                else:
+                    print(f"KaTeX error: {result.get('message')}")
+            except Exception as e:
+                if self.process and self.process.poll() is not None:
+                    stderr_content = self.process.stderr.read()
+                    if stderr_content:
+                        print(f"Renderer died with: {stderr_content.decode('utf-8', errors='replace')}")
+            return None
+
+    def on_post_page(self, output, page, config):
+        if not self.process:
+            return output
+
+        soup = BeautifulSoup(output, 'html.parser')
+        math_elements = soup.find_all(class_='arithmatex')
+        for el in math_elements:
+            content = el.get_text().strip()
+            display_mode = False
+            
+            if content.startswith('\\(') and content.endswith('\\)'):
+                latex = content[2:-2]
+            elif content.startswith('\\[') and content.endswith('\\]'):
+                latex = content[2:-2]
+                display_mode = True
+            elif content.startswith('$') and content.endswith('$'):
+                latex = content[1:-1]
+            elif content.startswith('$$') and content.endswith('$$'):
+                latex = content[2:-2]
+                display_mode = True
+            else:
+                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)
+
+        # Assets Injection
+        css_file = self.config['katex_css_filename']
+        if self.config['add_katex_css']:
+            if self.config['embed_assets'] and self._local_dist_path:
+                dest_path = self.config['copy_assets_to']
+                css_dest_file = f"{dest_path}/{css_file}"
+                css_url = get_relative_url(css_dest_file, page.url)
+                css_link = soup.new_tag('link', rel='stylesheet', href=css_url)
+                if soup.head:
+                    soup.head.append(css_link)
+                else:
+                    soup.insert(0, css_link)
+            else:
+                css_url = self._resolve_url(self.config['katex_dist'], css_file)
+                css_link = soup.new_tag('link', rel='stylesheet', href=css_url)
+                if soup.head:
+                    soup.head.append(css_link)
+                else:
+                    soup.insert(0, css_link)
+
+        # Inject ONLY client_scripts
+        for script_name in self.config['client_scripts']:
+            if '://' in script_name or script_name.endswith('.js'):
+                script_url = script_name
+            else:
+                if self.config['embed_assets'] and self._local_dist_path:
+                     dest_path = self.config['copy_assets_to']
+                     script_dest_file = f"{dest_path}/contrib/{script_name}.min.js"
+                     script_url = get_relative_url(script_dest_file, page.url)
+                else:
+                    script_url = self._resolve_url(self.config['katex_dist'], f'contrib/{script_name}.min.js')
+            
+            script_tag = soup.new_tag('script', src=script_url)
+            if soup.body:
+                soup.body.append(script_tag)
+            else:
+                soup.append(script_tag)
+
+        return str(soup)
+
+    def on_post_build(self, config):
+        if self.process:
+            self.process.terminate()
+            self.process.wait()
+        
+        # Copy assets if requested
+        if self.config['embed_assets'] and self._local_dist_path:
+            dest_dir = os.path.join(config['site_dir'], self.config['copy_assets_to'])
+            if not os.path.exists(dest_dir):
+                os.makedirs(dest_dir, exist_ok=True)
+            
+            # Copy katex CSS (filename depends on config)
+            css_file = self.config['katex_css_filename']
+            src_css = os.path.join(self._local_dist_path, css_file)
+            if os.path.exists(src_css):
+                shutil.copy2(src_css, dest_dir)
+            else:
+                print(f"Warning: Could not find {css_file} at {src_css}")
+            
+            # Copy fonts
+            src_fonts = os.path.join(self._local_dist_path, 'fonts')
+            dest_fonts = os.path.join(dest_dir, 'fonts')
+            if os.path.exists(src_fonts):
+                if os.path.exists(dest_fonts):
+                    shutil.rmtree(dest_fonts)
+                shutil.copytree(src_fonts, dest_fonts)
+            
+            # Copy requested client_scripts
+            dest_contrib = os.path.join(dest_dir, 'contrib')
+            if not os.path.exists(dest_contrib):
+                 os.makedirs(dest_contrib, exist_ok=True)
+            
+            # Note: We technically might need to copy items from ssr_contribs IF the user wanted them
+            # but we decided they are separate. However, if 'mhchem' is in ssr_contribs only,
+            # we don't copy it. If user wants it on client, they MUST put it in client_scripts.
+            for script_name in self.config['client_scripts']:
+                 if '://' not in script_name and not script_name.endswith('.js'):
+                     src_script = os.path.join(self._local_dist_path, 'contrib', f'{script_name}.min.js')
+                     if os.path.exists(src_script):
+                         shutil.copy2(src_script, dest_contrib)
+
+

mkdocs_katex_ssr-0.1.0/mkdocs_katex_ssr/renderer.js

@@ -0,0 +1,58 @@
+const katex = require('katex');
+const readline = require('readline');
+
+// Store loaded contrib names to avoid reloading
+const loadedContribs = new Set();
+
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false
+});
+
+rl.on('line', (line) => {
+    if (!line.trim()) return;
+    
+    try {
+        const data = JSON.parse(line);
+        
+        if (data.type === 'setup') {
+            if (data.contribs && Array.isArray(data.contribs)) {
+                data.contribs.forEach(name => {
+                    if (!loadedContribs.has(name)) {
+                        try {
+                            // Try to load from katex/dist/contrib/
+                            require(`katex/dist/contrib/${name}.js`);
+                            loadedContribs.add(name);
+                        } catch (e) {
+                            // Also try without .js or direct name if it's external
+                            try {
+                                require(name);
+                                loadedContribs.add(name);
+                            } catch (e2) {
+                                console.error(`Failed to load contrib: ${name}`);
+                            }
+                        }
+                    }
+                });
+            }
+            return; // No response needed for setup
+        }
+
+        if (data.type === 'render' || !data.type) {
+            const { latex, displayMode, options } = data;
+            
+            const html = katex.renderToString(latex, {
+                displayMode: displayMode || false,
+                throwOnError: false,
+                ...options
+            });
+            
+            process.stdout.write(JSON.stringify({ status: 'success', html }) + '\n');
+        }
+    } catch (err) {
+        process.stdout.write(JSON.stringify({ status: 'error', message: err.message }) + '\n');
+    }
+});
+
+console.error('KaTeX SSR Renderer started');

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

@@ -0,0 +1,10 @@
+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/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+mkdocs_katex_ssr/plugin.py
+mkdocs_katex_ssr/renderer.js
+mkdocs_katex_ssr.egg-info/PKG-INFO
+mkdocs_katex_ssr.egg-info/SOURCES.txt
+mkdocs_katex_ssr.egg-info/dependency_links.txt
+mkdocs_katex_ssr.egg-info/entry_points.txt
+mkdocs_katex_ssr.egg-info/requires.txt
+mkdocs_katex_ssr.egg-info/top_level.txt

mkdocs_katex_ssr-0.1.0/mkdocs_katex_ssr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mkdocs_katex_ssr-0.1.0/mkdocs_katex_ssr.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+katex-ssr = mkdocs_katex_ssr.plugin:KatexSsrPlugin

mkdocs_katex_ssr-0.1.0/mkdocs_katex_ssr.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mkdocs>=1.1.0
+beautifulsoup4>=4.9.0

mkdocs_katex_ssr-0.1.0/mkdocs_katex_ssr.egg-info/top_level.txt

@@ -0,0 +1 @@
+mkdocs_katex_ssr

mkdocs_katex_ssr-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mkdocs-katex-ssr"
+version = "0.1.0"
+description = "A MkDocs plugin for server-side rendering of KaTeX math."
+authors = [
+    {name = "Your Name", email = "your.email@example.com"}
+]
+license = {text = "MIT"}
+dependencies = [
+    "mkdocs>=1.1.0",
+    "beautifulsoup4>=4.9.0",
+]
+
+[project.entry-points."mkdocs.plugins"]
+katex-ssr = "mkdocs_katex_ssr.plugin:KatexSsrPlugin"
+
+[tool.setuptools]
+packages = ["mkdocs_katex_ssr"]
+
+[tool.setuptools.package-data]
+mkdocs_katex_ssr = ["renderer.js"]

mkdocs_katex_ssr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+