leafdocs 0.2.0__tar.gz → 0.3.0__tar.gz

{leafdocs-0.2.0/src/leafdocs.egg-info → leafdocs-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: leafdocs
-Version: 0.2.0
+Version: 0.3.0
 Summary: Turn a directory of Markdown files into a self-hosted, searchable web reader.
 Author-email: Anshul <you@example.com>
 License: MIT
@@ -17,6 +17,8 @@ Requires-Dist: markdown>=3.5
 Requires-Dist: python-frontmatter>=1.1
 Requires-Dist: bcrypt>=4.1
 Requires-Dist: python-dotenv>=1.0
+Requires-Dist: nh3>=0.2.22
+Requires-Dist: pymdown-extensions>=10.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-flask; extra == "dev"
@@ -56,7 +58,7 @@ ld = LeafDocs(docs_dir="./docs")
 ld.run()
 ```
 
-Visit `http://127.0.0.1:5000` — you'll see a searchable index of all `.md` files in your `docs/` directory.
+Visit `http://127.0.0.1:5000` to see a searchable index of all `.md` files in your `docs/` directory, including subfolders.
 
 ### Constructor arguments
 
@@ -103,6 +105,56 @@ Frontmatter is optional — files without it are discovered and served normally.
 
 ---
 
+## Folders and images
+
+Subfolders under `docs_dir` are shown on the index as a collapsible tree, folders first, then docs. Folder names are titlecased the same way as filenames (`getting-started` becomes `Getting Started`). Folders with no `.md` files anywhere beneath them are left out. While the search box has text, matching docs are shown with their folders opened; clearing it restores the folders you had open.
+
+A doc's URL is its path relative to `docs_dir` without `.md`, so `docs/guides/setup.md` is served at `/guides/setup`. Links ending in `.md`, such as `/guides/setup.md`, redirect to the same URL without it.
+
+Skipped during discovery and returned as 404 by the reader:
+
+- Any file or folder whose name starts with `.`, such as `.git/`
+- Top-level `login.md`, `logout.md`, and anything under `static/`, since those paths belong to built-in routes. Nested files such as `guides/login.md` are fine.
+
+Symlinks that point outside `docs_dir` are not listed and return 403.
+
+Images (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`) inside `docs_dir` are served at their path, behind the same login as the docs, so a doc can reference an image next to it with a relative path:
+
+```markdown
+![Diagram](diagram.png)
+```
+
+No other file types are served. SVG is excluded because it can carry scripts.
+
+---
+
+## Math and diagrams
+
+Docs can contain TeX math and [mermaid](https://mermaid.js.org) diagrams. Both are rendered in the browser by copies of [KaTeX](https://katex.org) and mermaid bundled with the package, so nothing is fetched from a CDN. Pages without math or diagrams load neither library.
+
+Inline math uses `\(...\)`. Single dollar signs are left alone so prices in prose render normally. Block math uses `$$...$$` or `\[...\]`:
+
+```markdown
+The area is \(\pi r^2\), and it costs $5.
+
+$$
+\int_0^1 x^2 \, dx = \frac{1}{3}
+$$
+```
+
+Diagrams are fenced code blocks tagged `mermaid`:
+
+````markdown
+```mermaid
+flowchart LR
+  Write --> Commit --> Read
+```
+````
+
+Mermaid runs with `securityLevel: "strict"`, so click handlers and raw HTML in diagram labels are disabled. Bundled versions and their licenses are listed in [`src/leafdocs/static/vendor/VERSIONS.md`](src/leafdocs/static/vendor/VERSIONS.md).
+
+---
+
 ## Authentication
 
 By default the server runs open with no login required.
@@ -117,7 +169,7 @@ Restart the server. All routes will now require a valid pin.
 
 **How it works:**
 - Pins are hashed with bcrypt at startup — raw values are never stored in memory
-- A successful login issues an `httponly` session cookie
+- A successful login issues a session cookie with `HttpOnly`, `SameSite=Lax`, and `Secure` (see `LEAFDOCS_COOKIE_SECURE` below)
 - Multiple pins are supported — useful for sharing access without a shared secret
 - To invalidate all sessions, rotate or remove the pin and restart
 
@@ -150,8 +202,17 @@ All pins and the secret key are configured via `.env` only. Copy `.env.example`
 ```
 LEAFDOCS_PINS=pin1,pin2
 LEAFDOCS_SECRET_KEY=your-secret-here
+LEAFDOCS_COOKIE_SECURE=true
+LEAFDOCS_ALLOW_HTML=false
 ```
 
+| Variable                 | Default | Description |
+|--------------------------|---------|-------------|
+| `LEAFDOCS_PINS`          | unset   | Comma-separated pins. Unset or empty means no auth. |
+| `LEAFDOCS_SECRET_KEY`    | random  | Session signing key. Random means sessions reset on restart. |
+| `LEAFDOCS_COOKIE_SECURE` | `true`  | Sets the `Secure` flag on the session cookie. `false`, `0`, `no`, or `off` disables it. Disable only when serving over plain HTTP, such as local or raw-IP testing; browsers will not send a `Secure` cookie over HTTP, so login loops back to the login page. |
+| `LEAFDOCS_ALLOW_HTML`    | `false` | Skips HTML sanitizing of rendered Markdown. `true`, `1`, `yes`, or `on` enables it. Only safe when you are the sole author of all content. |
+
 ---
 
 ## Known limitations
@@ -159,6 +220,7 @@ LEAFDOCS_SECRET_KEY=your-secret-here
 - **No caching** — Markdown is rendered on every request. Fine for personal or low-traffic use; not suitable for high-traffic production serving.
 - **No per-device session revocation** — rotating the pin invalidates all active sessions across all devices.
 - **No plugin system** — the primary extension hook is `ld.flask_app`. Add routes and middleware directly on the Flask app.
+- **Raw HTML in docs is sanitized** - rendered Markdown is passed through [nh3](https://github.com/messense/nh3) with an allowlist covering what the enabled extensions produce (headings with ids, lists, tables with alignment, code blocks with `language-*` classes, links, images, the `[TOC]` block, and `span` and `div` elements with class `arithmatex` for math). Scripts, event handler attributes, iframes, inline styles other than table alignment, and URL schemes other than `http`, `https`, and `mailto` are removed. Links get `rel="noopener noreferrer"`. Raw HTML outside the allowlist, such as `<details>`, is stripped, and `class` on `span` and `div` is removed unless it is exactly `arithmatex` (or `toc` on `div`). Set `LEAFDOCS_ALLOW_HTML=true` to turn sanitizing off; only do this when you are the sole author of all content.
 
 ---
 
@@ -190,6 +252,8 @@ pip install -e ".[dev]"
 pytest tests/ -v
 ```
 
+`python main.py` runs a dev server on http://127.0.0.1:5000 (cookie Secure flag is off for plain http).
+
 ---
 
 ## License

{leafdocs-0.2.0 → leafdocs-0.3.0}/README.md

@@ -32,7 +32,7 @@ ld = LeafDocs(docs_dir="./docs")
 ld.run()
 ```
 
-Visit `http://127.0.0.1:5000` — you'll see a searchable index of all `.md` files in your `docs/` directory.
+Visit `http://127.0.0.1:5000` to see a searchable index of all `.md` files in your `docs/` directory, including subfolders.
 
 ### Constructor arguments
 
@@ -79,6 +79,56 @@ Frontmatter is optional — files without it are discovered and served normally.
 
 ---
 
+## Folders and images
+
+Subfolders under `docs_dir` are shown on the index as a collapsible tree, folders first, then docs. Folder names are titlecased the same way as filenames (`getting-started` becomes `Getting Started`). Folders with no `.md` files anywhere beneath them are left out. While the search box has text, matching docs are shown with their folders opened; clearing it restores the folders you had open.
+
+A doc's URL is its path relative to `docs_dir` without `.md`, so `docs/guides/setup.md` is served at `/guides/setup`. Links ending in `.md`, such as `/guides/setup.md`, redirect to the same URL without it.
+
+Skipped during discovery and returned as 404 by the reader:
+
+- Any file or folder whose name starts with `.`, such as `.git/`
+- Top-level `login.md`, `logout.md`, and anything under `static/`, since those paths belong to built-in routes. Nested files such as `guides/login.md` are fine.
+
+Symlinks that point outside `docs_dir` are not listed and return 403.
+
+Images (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`) inside `docs_dir` are served at their path, behind the same login as the docs, so a doc can reference an image next to it with a relative path:
+
+```markdown
+![Diagram](diagram.png)
+```
+
+No other file types are served. SVG is excluded because it can carry scripts.
+
+---
+
+## Math and diagrams
+
+Docs can contain TeX math and [mermaid](https://mermaid.js.org) diagrams. Both are rendered in the browser by copies of [KaTeX](https://katex.org) and mermaid bundled with the package, so nothing is fetched from a CDN. Pages without math or diagrams load neither library.
+
+Inline math uses `\(...\)`. Single dollar signs are left alone so prices in prose render normally. Block math uses `$$...$$` or `\[...\]`:
+
+```markdown
+The area is \(\pi r^2\), and it costs $5.
+
+$$
+\int_0^1 x^2 \, dx = \frac{1}{3}
+$$
+```
+
+Diagrams are fenced code blocks tagged `mermaid`:
+
+````markdown
+```mermaid
+flowchart LR
+  Write --> Commit --> Read
+```
+````
+
+Mermaid runs with `securityLevel: "strict"`, so click handlers and raw HTML in diagram labels are disabled. Bundled versions and their licenses are listed in [`src/leafdocs/static/vendor/VERSIONS.md`](src/leafdocs/static/vendor/VERSIONS.md).
+
+---
+
 ## Authentication
 
 By default the server runs open with no login required.
@@ -93,7 +143,7 @@ Restart the server. All routes will now require a valid pin.
 
 **How it works:**
 - Pins are hashed with bcrypt at startup — raw values are never stored in memory
-- A successful login issues an `httponly` session cookie
+- A successful login issues a session cookie with `HttpOnly`, `SameSite=Lax`, and `Secure` (see `LEAFDOCS_COOKIE_SECURE` below)
 - Multiple pins are supported — useful for sharing access without a shared secret
 - To invalidate all sessions, rotate or remove the pin and restart
 
@@ -126,8 +176,17 @@ All pins and the secret key are configured via `.env` only. Copy `.env.example`
 ```
 LEAFDOCS_PINS=pin1,pin2
 LEAFDOCS_SECRET_KEY=your-secret-here
+LEAFDOCS_COOKIE_SECURE=true
+LEAFDOCS_ALLOW_HTML=false
 ```
 
+| Variable                 | Default | Description |
+|--------------------------|---------|-------------|
+| `LEAFDOCS_PINS`          | unset   | Comma-separated pins. Unset or empty means no auth. |
+| `LEAFDOCS_SECRET_KEY`    | random  | Session signing key. Random means sessions reset on restart. |
+| `LEAFDOCS_COOKIE_SECURE` | `true`  | Sets the `Secure` flag on the session cookie. `false`, `0`, `no`, or `off` disables it. Disable only when serving over plain HTTP, such as local or raw-IP testing; browsers will not send a `Secure` cookie over HTTP, so login loops back to the login page. |
+| `LEAFDOCS_ALLOW_HTML`    | `false` | Skips HTML sanitizing of rendered Markdown. `true`, `1`, `yes`, or `on` enables it. Only safe when you are the sole author of all content. |
+
 ---
 
 ## Known limitations
@@ -135,6 +194,7 @@ LEAFDOCS_SECRET_KEY=your-secret-here
 - **No caching** — Markdown is rendered on every request. Fine for personal or low-traffic use; not suitable for high-traffic production serving.
 - **No per-device session revocation** — rotating the pin invalidates all active sessions across all devices.
 - **No plugin system** — the primary extension hook is `ld.flask_app`. Add routes and middleware directly on the Flask app.
+- **Raw HTML in docs is sanitized** - rendered Markdown is passed through [nh3](https://github.com/messense/nh3) with an allowlist covering what the enabled extensions produce (headings with ids, lists, tables with alignment, code blocks with `language-*` classes, links, images, the `[TOC]` block, and `span` and `div` elements with class `arithmatex` for math). Scripts, event handler attributes, iframes, inline styles other than table alignment, and URL schemes other than `http`, `https`, and `mailto` are removed. Links get `rel="noopener noreferrer"`. Raw HTML outside the allowlist, such as `<details>`, is stripped, and `class` on `span` and `div` is removed unless it is exactly `arithmatex` (or `toc` on `div`). Set `LEAFDOCS_ALLOW_HTML=true` to turn sanitizing off; only do this when you are the sole author of all content.
 
 ---
 
@@ -166,6 +226,8 @@ pip install -e ".[dev]"
 pytest tests/ -v
 ```
 
+`python main.py` runs a dev server on http://127.0.0.1:5000 (cookie Secure flag is off for plain http).
+
 ---
 
 ## License

{leafdocs-0.2.0 → leafdocs-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "leafdocs"
-version = "0.2.0"
+version = "0.3.0"
 description = "Turn a directory of Markdown files into a self-hosted, searchable web reader."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -23,6 +23,8 @@ dependencies = [
     "python-frontmatter>=1.1",
     "bcrypt>=4.1",
     "python-dotenv>=1.0",
+    "nh3>=0.2.22",
+    "pymdown-extensions>=10.0",
 ]
 
 [project.optional-dependencies]

leafdocs-0.3.0/src/leafdocs/app.py

@@ -0,0 +1,347 @@
+import os
+import pathlib
+import hashlib
+import re
+import secrets
+
+import bcrypt
+import frontmatter
+import markdown
+import nh3
+from dotenv import load_dotenv
+from flask import (
+    Flask,
+    abort,
+    redirect,
+    render_template,
+    request,
+    send_file,
+    session,
+    url_for,
+)
+
+load_dotenv()
+
+
+def _load_pins() -> list[bytes]:
+    """Read LEAFDOCS_PINS from env, hash each with bcrypt, return list of hashes."""
+    raw = os.getenv("LEAFDOCS_PINS", "").strip()
+    if not raw:
+        return []
+    pins = [p.strip() for p in raw.split(",") if p.strip()]
+    return [bcrypt.hashpw(p.encode(), bcrypt.gensalt()) for p in pins]
+
+
+def _verify_pin(candidate: str, hashes: list[bytes]) -> bool:
+    return any(bcrypt.checkpw(candidate.encode(), h) for h in hashes)
+
+
+_MARKDOWN_EXTENSIONS = ["fenced_code", "tables", "toc", "nl2br", "pymdownx.arithmatex"]
+# Generic mode emits plain span/div.arithmatex wrappers for a client-side renderer (KaTeX).
+# Inline math is \(...\) only, so single dollar signs in prose (prices) stay plain text.
+_MARKDOWN_EXTENSION_CONFIGS = {"pymdownx.arithmatex": {"generic": True, "inline_syntax": ["round"]}}
+
+# Everything the enabled Markdown extensions (fenced_code, tables, toc, nl2br, arithmatex) emit
+_ALLOWED_TAGS = {
+    "h1", "h2", "h3", "h4", "h5", "h6",
+    "p", "br", "hr", "ul", "ol", "li", "blockquote", "pre", "code",
+    "table", "thead", "tbody", "tr", "th", "td",
+    "em", "strong", "del", "a", "img", "div", "span",
+}
+_ALLOWED_ATTRIBUTES = {
+    **{h: {"id"} for h in ("h1", "h2", "h3", "h4", "h5", "h6")},
+    "a": {"href", "title"},
+    "img": {"src", "alt", "title"},
+    "code": {"class"},
+    "div": {"class"},
+    "span": {"class"},
+    "th": {"style"},
+    "td": {"style"},
+}
+_LANGUAGE_CLASS = re.compile(r"language-[\w+#.-]+")
+
+
+def _filter_attribute(tag: str, attr: str, value: str) -> str | None:
+    """Restrict class values to what fenced_code (language-*), toc (toc) and arithmatex produce."""
+    if attr == "class":
+        if tag == "code" and _LANGUAGE_CLASS.fullmatch(value):
+            return value
+        if tag == "div" and value in ("toc", "arithmatex"):
+            return value
+        if tag == "span" and value == "arithmatex":
+            return value
+        return None
+    return value
+
+
+def _sanitize(html: str) -> str:
+    return nh3.clean(
+        html,
+        tags=_ALLOWED_TAGS,
+        attributes=_ALLOWED_ATTRIBUTES,
+        attribute_filter=_filter_attribute,
+        filter_style_properties={"text-align"},
+        url_schemes={"http", "https", "mailto"},
+        link_rel="noopener noreferrer",
+    )
+
+
+_IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".gif", ".webp"}
+
+# Top-level slugs that would collide with built-in routes
+_RESERVED_SLUGS = {"login", "logout"}
+
+
+def _slug(filepath: pathlib.Path, docs_dir: pathlib.Path) -> str:
+    """Convert a .md filepath to its URL slug (posix path relative to docs_dir, no .md)."""
+    return filepath.relative_to(docs_dir).with_suffix("").as_posix()
+
+
+def _display_name(name: str) -> str:
+    """Titlecase a file stem or directory name, treating - and _ as spaces."""
+    return name.replace("-", " ").replace("_", " ").title()
+
+
+def _doc_meta(post: frontmatter.Post, md_file: pathlib.Path) -> tuple[str, list[str]]:
+    """Return (title, tags) from frontmatter, falling back to the filename for title."""
+    title = post.get("title") or _display_name(md_file.stem)
+    tags = post.get("tags") or []
+    if isinstance(tags, str):
+        tags = [t.strip() for t in tags.split(",")]
+    return title, tags
+
+
+def _is_hidden(rel: pathlib.PurePath) -> bool:
+    return any(part.startswith(".") for part in rel.parts)
+
+
+def _is_reserved(slug: str) -> bool:
+    return slug in _RESERVED_SLUGS or slug.startswith("static/")
+
+
+def _is_inside(path: pathlib.Path, docs_dir: pathlib.Path) -> bool:
+    """True if path, with symlinks resolved, is still inside docs_dir."""
+    try:
+        path.resolve().relative_to(docs_dir)
+    except ValueError:
+        return False
+    return True
+
+
+def _discover_docs(docs_dir: pathlib.Path) -> list[dict]:
+    """
+    Recursively scan docs_dir for .md files. Return list of dicts with:
+      slug, title, tags, path
+    Sorted alphabetically by title. Hidden paths, symlinks that escape
+    docs_dir, and reserved slugs are skipped.
+    """
+    docs = []
+    for md_file in sorted(docs_dir.rglob("*.md")):
+        if _is_hidden(md_file.relative_to(docs_dir)):
+            continue
+        if not md_file.is_file() or not _is_inside(md_file, docs_dir):
+            continue
+        slug = _slug(md_file, docs_dir)
+        if _is_reserved(slug):
+            continue
+        post = frontmatter.load(str(md_file))
+        title, tags = _doc_meta(post, md_file)
+        docs.append(
+            {
+                "slug": slug,
+                "title": title,
+                "tags": tags,
+                "path": md_file,
+            }
+        )
+    docs.sort(key=lambda d: d["title"].lower())
+    return docs
+
+
+def _build_tree(docs: list[dict]) -> dict:
+    """
+    Group docs into nested folders by slug. Each node has:
+      name, title, folders, docs
+    Folders come sorted by name and docs by title, both case-insensitive.
+    Only folders that hold docs somewhere beneath them exist.
+    """
+    def new_node(name: str) -> dict:
+        return {"name": name, "title": _display_name(name), "folders": {}, "docs": []}
+
+    root = new_node("")
+    for doc in docs:
+        node = root
+        for part in doc["slug"].split("/")[:-1]:
+            node = node["folders"].setdefault(part, new_node(part))
+        node["docs"].append(doc)
+
+    def finish(node: dict) -> dict:
+        node["folders"] = [finish(f) for f in sorted(node["folders"].values(), key=lambda f: f["name"].lower())]
+        node["docs"].sort(key=lambda d: d["title"].lower())
+        return node
+
+    return finish(root)
+
+
+class LeafDocs:
+    def __init__(
+        self,
+        docs_dir: str = "./docs",
+        secret_key: str | None = None,
+    ):
+        self.docs_dir = pathlib.Path(docs_dir).resolve()
+        if not self.docs_dir.exists():
+            raise FileNotFoundError(f"docs_dir not found: {self.docs_dir}")
+
+        self._pin_hashes = _load_pins()
+        self._auth_enabled = bool(self._pin_hashes)
+
+        self.flask_app = Flask(__name__)
+        self.flask_app.secret_key = secret_key or os.getenv("LEAFDOCS_SECRET_KEY") or secrets.token_hex(32)
+
+        # Secure by default; only an explicit false-like value disables it (plain HTTP setups)
+        cookie_secure = os.getenv("LEAFDOCS_COOKIE_SECURE", "").strip().lower() not in ("false", "0", "no", "off")
+        self.flask_app.config.update(
+            SESSION_COOKIE_HTTPONLY=True,
+            SESSION_COOKIE_SECURE=cookie_secure,
+            SESSION_COOKIE_SAMESITE="Lax",
+        )
+
+        # Off by default; raw HTML in docs is only safe when every author is trusted
+        self._allow_html = os.getenv("LEAFDOCS_ALLOW_HTML", "").strip().lower() in ("true", "1", "yes", "on")
+
+        self._register_routes()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _is_authenticated(self) -> bool:
+        if not self._auth_enabled:
+            return True
+        return session.get("authenticated") is True
+
+    def _require_auth(self):
+        if not self._is_authenticated():
+            return redirect(url_for("login"))
+        return None
+
+    def _serve_image(self, slug: str):
+        """Serve an image file from docs_dir. Caller has already checked auth."""
+        rel = pathlib.PurePosixPath(slug)
+        if _is_hidden(rel):
+            abort(404)
+        image = self.docs_dir / rel
+        if not image.is_file():
+            abort(404)
+        if not _is_inside(image, self.docs_dir):
+            abort(403)
+        return send_file(image.resolve())
+
+    # ------------------------------------------------------------------
+    # Route registration
+    # ------------------------------------------------------------------
+
+    def _register_routes(self):
+        app = self.flask_app
+
+        # Attach self so inner functions can reference it
+        leafdocs = self
+
+        @app.route("/login", methods=["GET", "POST"])
+        def login():
+            if not leafdocs._auth_enabled:
+                return redirect(url_for("index"))
+
+            error = None
+            if request.method == "POST":
+                pin = request.form.get("pin", "")
+                if _verify_pin(pin, leafdocs._pin_hashes):
+                    session["authenticated"] = True
+                    session.permanent = False
+                    return redirect(url_for("index"))
+                error = "Incorrect pin."
+
+            return render_template("login.html", error=error)
+
+        @app.route("/logout")
+        def logout():
+            session.clear()
+            return redirect(url_for("login"))
+
+        @app.route("/")
+        def index():
+            redir = leafdocs._require_auth()
+            if redir:
+                return redir
+            docs = _discover_docs(leafdocs.docs_dir)
+            return render_template(
+                "index.html",
+                docs=docs,
+                tree=_build_tree(docs),
+                auth_enabled=leafdocs._auth_enabled,
+            )
+
+        @app.route("/<path:slug>")
+        def reader(slug: str):
+            redir = leafdocs._require_auth()
+            if redir:
+                return redir
+
+            # Old-style links to the .md file land on the doc itself
+            if slug.endswith(".md"):
+                if not slug[:-3]:
+                    abort(404)
+                return redirect(url_for("reader", slug=slug[:-3]))
+
+            if pathlib.PurePosixPath(slug).suffix.lower() in _IMAGE_SUFFIXES:
+                return leafdocs._serve_image(slug)
+
+            rel = pathlib.PurePosixPath(f"{slug}.md")
+            if _is_hidden(rel) or _is_reserved(rel.as_posix()[:-3]):
+                abort(404)
+
+            # Find matching file
+            md_file = leafdocs.docs_dir / rel
+            if not md_file.is_file():
+                abort(404)
+
+            # Security: ensure resolved path is still inside docs_dir
+            if not _is_inside(md_file, leafdocs.docs_dir):
+                abort(403)
+
+            post = frontmatter.load(str(md_file))
+            title, tags = _doc_meta(post, md_file)
+            crumbs = [_display_name(part) for part in rel.parts[:-1]]
+
+            html_content = markdown.markdown(
+                post.content,
+                extensions=_MARKDOWN_EXTENSIONS,
+                extension_configs=_MARKDOWN_EXTENSION_CONFIGS,
+            )
+            if not leafdocs._allow_html:
+                html_content = _sanitize(html_content)
+
+            # Load the KaTeX and mermaid assets only on pages that need them. Match whole
+            # opening tags: text like `class="arithmatex"` in a code span keeps its quotes,
+            # but its < is always escaped, so it cannot match.
+            has_math = '<span class="arithmatex">' in html_content or '<div class="arithmatex">' in html_content
+            has_mermaid = '<code class="language-mermaid">' in html_content
+
+            return render_template(
+                "reader.html",
+                title=title,
+                tags=tags,
+                crumbs=crumbs,
+                content=html_content,
+                has_math=has_math,
+                has_mermaid=has_mermaid,
+                auth_enabled=leafdocs._auth_enabled,
+            )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def run(self, host: str = "127.0.0.1", port: int = 5000, **kwargs):
+        self.flask_app.run(host=host, port=port, **kwargs)

leafdocs-0.3.0/src/leafdocs/static/reader-render.js

@@ -0,0 +1,61 @@
+// Client-side rendering for the reader view. reader.html loads the KaTeX and
+// mermaid vendor scripts only on pages that need them, so each part below
+// runs only when its library is present.
+(function () {
+  // Math: arithmatex (generic mode) wraps TeX in \( \) or \[ \] inside
+  // .arithmatex elements. Render only there, never the whole page.
+  if (window.renderMathInElement) {
+    document.querySelectorAll('.arithmatex').forEach(function (el) {
+      window.renderMathInElement(el, {
+        delimiters: [
+          { left: '\\(', right: '\\)', display: false },
+          { left: '\\[', right: '\\]', display: true },
+        ],
+        throwOnError: false,
+      });
+    });
+  }
+
+  // Diagrams: fenced_code emits <pre><code class="language-mermaid">.
+  // Copy the source as text (never as HTML) into the <pre class="mermaid">
+  // element mermaid expects.
+  if (window.mermaid) {
+    document.querySelectorAll('pre > code.language-mermaid').forEach(function (code) {
+      var pre = document.createElement('pre');
+      pre.className = 'mermaid';
+      pre.textContent = code.textContent;
+      code.parentElement.replaceWith(pre);
+    });
+
+    // Theme colors come from the palette variables in base.html
+    var css = getComputedStyle(document.documentElement);
+    var color = function (name) { return css.getPropertyValue(name).trim(); };
+
+    window.mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: 'strict',
+      theme: 'base',
+      themeVariables: {
+        darkMode: true,
+        background: color('--bg'),
+        fontFamily: color('--font-ui'),
+        textColor: color('--text'),
+        primaryColor: color('--surface'),
+        primaryTextColor: color('--text'),
+        primaryBorderColor: color('--accent'),
+        secondaryColor: color('--tag-bg'),
+        secondaryTextColor: color('--tag-text'),
+        secondaryBorderColor: color('--accent-dim'),
+        tertiaryColor: color('--bg'),
+        tertiaryTextColor: color('--text'),
+        tertiaryBorderColor: color('--border'),
+        lineColor: color('--muted'),
+        edgeLabelBackground: color('--surface'),
+        noteBkgColor: color('--surface'),
+        noteTextColor: color('--text'),
+        noteBorderColor: color('--border'),
+      },
+    });
+    window.mermaid.run({ querySelector: 'pre.mermaid' });
+  }
+})();