mkdocs-treeview 0.1.0__py3-none-any.whl

mkdocs_treeview/css_generator.py

@@ -0,0 +1,92 @@
+"""
+CSS generator for treeview icons.
+
+Supports three icon_mode values:
+- files: relative URL to copied SVG assets
+- embedded: base64 data URI inline in CSS
+- cdn: jsDelivr CDN URL (no local files needed)
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+CDN_BASE = "https://cdn.jsdelivr.net/npm/vscode-material-icon-theme@{version}/icons"
+DEFAULT_CDN_VERSION = "5.35.0"
+
+_BASE_CSS = """\
+/* mkdocs-treeview — generated, do not edit */
+.treeview { font-family: monospace; line-height: 1.1; }
+.tv-line { display: flex; align-items: center; }
+.tv-line-element { display: contents; }
+.tv-item-name { margin-left: 5px; }
+.tv-icon {
+  width: 18px;
+  height: 18px;
+  flex-shrink: 0;
+  background-repeat: no-repeat;
+  background-size: contain;
+}
+"""
+
+_DARK_SELECTOR = '[data-md-color-scheme="slate"]'
+
+
+def generate_css(
+    icons: list[tuple[str, str, str]],
+    icon_mode: str,
+    icons_dir: Path | None = None,
+    assets_path: str = "assets/treeview/icons",
+    cdn_version: str = DEFAULT_CDN_VERSION,
+) -> str:
+    """
+    Generate CSS for the given list of (css_class, dark_svg, light_svg) tuples.
+
+    icons_dir: path to the local icons directory (required for 'embedded' mode).
+    assets_path: URL path used in 'files' mode CSS rules.
+    """
+    parts = [_BASE_CSS]
+
+    for css_class, dark_svg, light_svg in icons:
+        dark_url = _resolve_url(dark_svg, icon_mode, icons_dir, assets_path, cdn_version)
+        if dark_url is None:
+            continue
+
+        parts.append(f".{css_class} {{ background-image: url('{dark_url}'); }}")
+
+        # Light mode override: Material uses [data-md-color-scheme="slate"] for dark,
+        # so the "default" scheme is light. We emit a light override for the default scheme.
+        if light_svg != dark_svg:
+            light_url = _resolve_url(light_svg, icon_mode, icons_dir, assets_path, cdn_version)
+            if light_url:
+                parts.append(
+                    f":root:not({_DARK_SELECTOR}) .{css_class} "
+                    f"{{ background-image: url('{light_url}'); }}"
+                )
+
+    return "\n".join(parts) + "\n"
+
+
+def _resolve_url(
+    svg_name: str,
+    icon_mode: str,
+    icons_dir: Path | None,
+    assets_path: str,
+    cdn_version: str,
+) -> str | None:
+    if icon_mode == "cdn":
+        base = CDN_BASE.format(version=cdn_version)
+        return f"{base}/{svg_name}"
+
+    if icon_mode == "embedded":
+        if icons_dir is None:
+            return None
+        svg_path = icons_dir / svg_name
+        if not svg_path.exists():
+            return None
+        data = base64.b64encode(svg_path.read_bytes()).decode()
+        return f"data:image/svg+xml;base64,{data}"
+
+    # files mode
+    return f"{assets_path}/{svg_name}"

mkdocs_treeview/extension.py

@@ -0,0 +1,144 @@
+"""
+Python-Markdown extension for treeview fenced code blocks.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from markdown import Extension
+from markdown.postprocessors import Postprocessor
+from markdown.preprocessors import Preprocessor
+
+from mkdocs_treeview.css_generator import generate_css
+from mkdocs_treeview.parser import parse
+from mkdocs_treeview.renderer import IconRegistry, render
+
+FENCE_RE = re.compile(r"^```treeview\s*$")
+FENCE_END_RE = re.compile(r"^```\s*$")
+
+ICONS_PKG_DIR = Path(__file__).parent / "icons"
+
+
+class TreeviewPreprocessor(Preprocessor):
+    """Preprocessor that handles ```treeview fenced code blocks."""
+
+    def __init__(self, md: Any, registry: IconRegistry):
+        super().__init__(md)
+        self.registry = registry
+
+    def run(self, lines: list[str]) -> list[str]:
+        new_lines: list[str] = []
+        i = 0
+        while i < len(lines):
+            if FENCE_RE.match(lines[i]):
+                block_lines = []
+                i += 1
+                while i < len(lines) and not FENCE_END_RE.match(lines[i]):
+                    block_lines.append(lines[i])
+                    i += 1
+                # If loop ended without finding closing fence, treat gathered
+                # lines as the block content (unclosed fence is handled gracefully).
+                source = "\n".join(block_lines)
+                try:
+                    root = parse(source)
+                    html = render(root, self.registry)
+                    placeholder = self.md.htmlStash.store(html)
+                    # Blank lines around placeholder prevent <p> wrapping
+                    new_lines.extend(["", placeholder, ""])
+                except Exception as exc:
+                    err = f'<div class="treeview-error">treeview parse error: {exc}</div>'
+                    placeholder = self.md.htmlStash.store(err)
+                    new_lines.extend(["", placeholder, ""])
+            else:
+                new_lines.append(lines[i])
+            i += 1
+        return new_lines
+
+
+class TreeviewCSSPostprocessor(Postprocessor):
+    """Writes a lean CSS file containing only the icons used so far.
+
+    Registered when css_output_path is set on TreeviewExtension. Since
+    Zensical (and similar pipelines) create a new Markdown() instance per
+    page, this runs after every page. The registry accumulates icons across
+    all pages; each write overwrites the previous file. By the last page the
+    file contains exactly the icons referenced across the whole site.
+    """
+
+    def __init__(
+        self,
+        md: Any,
+        registry: IconRegistry,
+        css_output_path: Path,
+        icon_mode: str,
+        icons_dir: Path,
+    ):
+        super().__init__(md)
+        self.registry = registry
+        self.css_output_path = css_output_path
+        self.icon_mode = icon_mode
+        self.icons_dir = icons_dir
+
+    def run(self, text: str) -> str:
+        icons = self.registry.items()
+        if icons:
+            self.css_output_path.parent.mkdir(parents=True, exist_ok=True)
+            css = generate_css(
+                icons=icons,
+                icon_mode=self.icon_mode,
+                icons_dir=self.icons_dir if self.icon_mode == "embedded" else None,
+                assets_path="icons",
+            )
+            self.css_output_path.write_text(css, encoding="utf-8")
+        return text
+
+
+class TreeviewExtension(Extension):
+    """Markdown extension for treeview code blocks.
+
+    Optional kwargs (used when the extension is loaded without the MkDocs
+    plugin, e.g. directly in Zensical):
+
+    - registry: IconRegistry — shared across pages; created if not provided
+    - css_output_path: str|Path — if set, a CSS file is written here after
+      each page, containing only the icons used so far (dynamic, lean output)
+    - icon_mode: str — "embedded" (default) or "files"; controls CSS format
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self.registry: IconRegistry = kwargs.pop("registry", None) or IconRegistry()
+        self._css_output_path: Path | None = (
+            Path(kwargs.pop("css_output_path")) if "css_output_path" in kwargs else None
+        )
+        self._icon_mode: str = kwargs.pop("icon_mode", "embedded")
+        super().__init__(**kwargs)
+
+    def extendMarkdown(self, md: Any) -> None:
+        md.preprocessors.register(
+            TreeviewPreprocessor(md, self.registry),
+            "treeview",
+            # Priority 27: runs AFTER normalize_whitespace (30) so STX/ETX
+            # stash placeholders are not stripped, and BEFORE html_block (20)
+            # so treeview claims its blocks first.
+            27,
+        )
+        if self._css_output_path is not None:
+            md.postprocessors.register(
+                TreeviewCSSPostprocessor(
+                    md,
+                    self.registry,
+                    self._css_output_path,
+                    self._icon_mode,
+                    ICONS_PKG_DIR,
+                ),
+                "treeview_css",
+                # Priority 0: run last, after all HTML is finalised.
+                0,
+            )
+
+
+def makeExtension(**kwargs: object) -> TreeviewExtension:
+    return TreeviewExtension(**kwargs)

mkdocs_treeview/icon_finder.py

@@ -0,0 +1,87 @@
+"""
+Icon lookup for file and folder names.
+
+Priority order for files:
+1. Exact file name match, case-insensitive (e.g. Dockerfile, .gitignore)
+2. Single extension match, case-insensitive (e.g. .py -> python)
+3. Language ID match
+4. Fallback to generic file icon
+
+For folders:
+1. Exact folder name match
+2. Fallback to generic folder icon
+
+Returns (dark_svg, light_svg) tuples. If no light variant exists, dark is used for both.
+"""
+
+from __future__ import annotations
+
+try:
+    from mkdocs_treeview.icon_map import (
+        FILE_EXT1,
+        FILE_EXT1_LIGHT,
+        FILE_NAMES,
+        FILE_NAMES_LIGHT,
+        FOLDER_NAMES,
+        FOLDER_NAMES_LIGHT,
+        LANGUAGE_IDS,
+    )
+except ImportError:
+    # icon_map.py not yet generated; return empty maps so tests can stub them
+    FILE_NAMES = FILE_NAMES_LIGHT = {}
+    FILE_EXT1 = FILE_EXT1_LIGHT = {}
+    FOLDER_NAMES = FOLDER_NAMES_LIGHT = {}
+    LANGUAGE_IDS = {}
+
+DEFAULT_FILE = "file.svg"
+DEFAULT_FOLDER = "folder.svg"
+
+
+def get_icon_for_file(name: str) -> tuple[str, str]:
+    """Return (dark_svg, light_svg) for a file name."""
+    name_lower = name.lower()
+
+    # 1. Exact file name, case-insensitive (Dockerfile, .gitignore, tsconfig.json)
+    if name_lower in FILE_NAMES:
+        dark = FILE_NAMES[name_lower]
+        light = FILE_NAMES_LIGHT.get(name_lower, dark)
+        return dark, light
+
+    # 2. Single extension, case-insensitive
+    if "." in name:
+        ext = name.rsplit(".", 1)[-1].lower()
+        if ext in FILE_EXT1:
+            dark = FILE_EXT1[ext]
+            light = FILE_EXT1_LIGHT.get(ext, dark)
+            return dark, light
+
+        # 3. Language ID
+        if ext in LANGUAGE_IDS:
+            dark = LANGUAGE_IDS[ext]
+            return dark, dark
+
+    return DEFAULT_FILE, DEFAULT_FILE
+
+
+def get_icon_for_folder(name: str) -> tuple[str, str]:
+    """Return (dark_svg, light_svg) for a folder name (without trailing slash)."""
+    name = name.rstrip("/")
+    if name in FOLDER_NAMES:
+        dark = FOLDER_NAMES[name]
+        light = FOLDER_NAMES_LIGHT.get(name, dark)
+        return dark, light
+    return DEFAULT_FOLDER, DEFAULT_FOLDER
+
+
+def get_icon_for_open_folder(name: str) -> tuple[str, str]:
+    """Return open-variant (dark_svg, light_svg) for a folder that has children.
+
+    The vscode-material-icon-theme raw icons/ directory does not include
+    pre-built -open variants. We derive the open icon name from the closed
+    one and fall back to the closed icon if the open variant is not available.
+    The CSS generator skips copying icons that don't exist on disk.
+    """
+    dark, light = get_icon_for_folder(name)
+    dark_open = dark.replace(".svg", "-open.svg")
+    light_open = light.replace(".svg", "-open.svg")
+    return dark_open, light_open