mkdocs-treeview 0.1.0__tar.gz

mkdocs_treeview-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+site/
+*.egg
+.ruff_cache/
+.mypy_cache/
+.claude/

mkdocs_treeview-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        language: system
+        entry: uv run ruff format
+        types: [python]
+
+      - id: ruff-check
+        name: ruff lint
+        language: system
+        entry: uv run ruff check --fix
+        types: [python]
+
+      - id: mypy
+        name: mypy
+        language: system
+        entry: uv run mypy mkdocs_treeview/
+        pass_filenames: false
+
+      - id: pytest-unit
+        name: unit tests
+        language: system
+        entry: uv run pytest tests/unit/ -q
+        pass_filenames: false

mkdocs_treeview-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.1.0] - 2026-06-07
+
+Initial release.
+
+### Added
+
+- Renders ` ```treeview ` fenced code blocks as styled file trees in MkDocs, Material for MkDocs, and Zensical
+- ASCII-tree format support (output of the `tree` command: `├──`, `│`, `└──`)
+- Symbol-based format support (repeating `*` or `#` markers for depth)
+- Material icon theme icons — automatically chosen by file extension, file name, or folder name
+- Open/closed folder icon variants based on whether a folder has children
+- Three asset modes: `files` (local SVGs), `embedded` (base64 in CSS), `cdn` (jsDelivr)
+- Dynamic CSS generation — only icons actually used in a site are emitted (~7 KB instead of 1.3 MB)
+- Dark/light mode support via separate light-variant icons for `[data-md-color-scheme="slate"]`
+- MkDocs plugin (`treeview`) that auto-registers the extension and injects CSS
+- Standalone Markdown extension for use without the MkDocs plugin (e.g. Zensical)
+- Unit and integration test suites covering parser, renderer, CSS generator, and full demo builds
+- Ruff (formatter + linter) and mypy type checking configured in `pyproject.toml`
+- Pre-commit hooks for ruff, mypy, and unit tests

mkdocs_treeview-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lasse Knudsen
+
+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_treeview-0.1.0/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: mkdocs-treeview
+Version: 0.1.0
+Summary: MkDocs plugin and Markdown extension for rendering ASCII file trees with material icons
+License: MIT License
+        
+        Copyright (c) 2026 Lasse Knudsen
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: markdown>=3.4
+Requires-Dist: mkdocs>=1.5
+Description-Content-Type: text/markdown
+
+# mkdocs-treeview
+
+A Python-Markdown extension and MkDocs plugin that renders ASCII file trees with
+[Material icon theme](https://github.com/material-extensions/vscode-material-icon-theme) icons.
+Works with MkDocs, Material for MkDocs, and Zensical.
+
+Inspired by [asciidoctor-treeview](https://github.com/lask79/asciidoctor-treeview).
+
+````markdown
+```treeview
+├── src/
+│   ├── main.py
+│   └── utils.py
+├── tests/
+│   └── test_main.py
+├── Dockerfile
+├── tsconfig.json
+└── README.md
+```
+````
+
+| Light | Dark |
+|:---:|:---:|
+| ![Treeview light theme](docs/images/treeview-light.png) | ![Treeview dark theme](docs/images/treeview-dark.png) |
+
+---
+
+## Features
+
+- Renders ` ```treeview ` fenced code blocks as styled file trees
+- Icons automatically chosen by file extension, file name, or folder name
+- Supports ASCII-tree format (`tree` command output) and symbol-based (`*`/`#`) format
+- Dynamic CSS — only icons actually used in your site are emitted (~7 KB instead of 1.3 MB)
+- Dark/light mode: separate light-variant icons for `[data-md-color-scheme="slate"]`
+- Three asset modes: `files` (local SVGs), `embedded` (base64 in CSS), `cdn` (jsDelivr)
+
+---
+
+## Installation
+
+```bash
+pip install mkdocs-treeview
+```
+
+---
+
+## Usage
+
+Write an ASCII tree in a fenced code block tagged `treeview`:
+
+````markdown
+```treeview
+├── src/
+│   ├── main.py
+│   └── utils.py
+├── tests/
+│   └── test_main.py
+├── Dockerfile
+├── tsconfig.json
+└── README.md
+```
+````
+
+Both formats are accepted:
+
+**ASCII-tree** (output of the `tree` command):
+```
+├── src/
+│   └── main.py
+└── README.md
+```
+
+**Symbol-based** (indent depth = number of markers):
+```
+* src/
+** main.py
+* README.md
+```
+
+---
+
+## Configuration
+
+### MkDocs (`mkdocs.yml`)
+
+```yaml
+plugins:
+  - treeview:
+      icon_mode: files   # files | embedded | cdn   (default: files)
+```
+
+The plugin registers the Markdown extension automatically and injects
+`assets/treeview/treeview.css` into `extra_css`. No other configuration needed.
+
+### Material for MkDocs (`mkdocs.yml`)
+
+Identical to the MkDocs configuration — the plugin works with any MkDocs theme:
+
+```yaml
+theme:
+  name: material
+
+plugins:
+  - treeview:
+      icon_mode: embedded
+```
+
+### Zensical (`zensical.toml`)
+
+Add the extension via `markdown_extensions` and point `extra_css` at the output file:
+
+```toml
+[project]
+extra_css = ["stylesheets/treeview.css"]
+
+[project.markdown_extensions."mkdocs_treeview.extension"]
+css_output_path = "docs/stylesheets/treeview.css"
+icon_mode = "embedded"
+```
+
+`css_output_path` is resolved relative to the directory where `zensical build` is
+run (the project root). The extension writes a lean CSS file there after each page.
+
+---
+
+## Asset modes
+
+| Mode | Behavior | Best for |
+|---|---|---|
+| `files` | SVGs copied to `assets/treeview/icons/`, CSS uses relative URLs | Production MkDocs sites |
+| `embedded` | SVGs inlined as base64 data URIs — single self-contained CSS file | Zensical, offline output |
+| `cdn` | CSS references jsDelivr URLs — no local files | Quick preview, GitHub rendering |
+
+---
+
+## How it works
+
+The MkDocs plugin hooks into `on_config` to register the Markdown extension and
+inject `extra_css`. During the build each page's treeview blocks are converted to
+HTML with `tv-icon tv-icon-<name>` CSS classes. After the build, `on_post_build`
+writes a lean CSS file containing only the icons that were actually rendered.
+
+For Zensical, `TreeviewCSSPostprocessor` writes the CSS file after every page.
+Because the extension object persists across all `render()` calls, the registry
+accumulates icons across pages. The final write contains the complete lean CSS.
+
+---
+
+## HTML output
+
+The renderer emits flat `<span class="tv-line">` rows with ASCII prefix connectors
+(matching the asciidoctor-treeview approach), rather than a nested `<ul>/<li>` tree:
+
+```html
+<div class="treeview">
+  <span class="tv-line">
+    <span class="tv-line-prefix">├──&nbsp;</span>
+    <span class="tv-line-element">
+      <i class="tv-icon tv-icon-folder-src-open"></i>
+      <span class="tv-item-name">src/</span>
+    </span>
+  </span>
+  <span class="tv-line">
+    <span class="tv-line-prefix">│&nbsp;&nbsp;&nbsp;├──&nbsp;</span>
+    <span class="tv-line-element">
+      <i class="tv-icon tv-icon-python"></i>
+      <span class="tv-item-name">main.py</span>
+    </span>
+  </span>
+  <span class="tv-line">
+    <span class="tv-line-prefix">│&nbsp;&nbsp;&nbsp;└──&nbsp;</span>
+    <span class="tv-line-element">
+      <i class="tv-icon tv-icon-python"></i>
+      <span class="tv-item-name">utils.py</span>
+    </span>
+  </span>
+  <span class="tv-line">
+    <span class="tv-line-prefix">└──&nbsp;</span>
+    <span class="tv-line-element">
+      <i class="tv-icon tv-icon-readme"></i>
+      <span class="tv-item-name">README.md</span>
+    </span>
+  </span>
+</div>
+```
+
+Folders with children use the open variant (`folder-src-open.svg`); leaf folders
+use the closed variant. Unknown file types fall back to a generic file icon.
+
+---
+
+## Development
+
+### Requirements
+
+- Python >= 3.9
+- [uv](https://docs.astral.sh/uv/) (recommended)
+- Node.js / npm (only for `scripts/build_icons.py` — regenerating the icon bundle)
+
+### Setup
+
+```bash
+uv sync
+```
+
+### Run tests
+
+```bash
+uv run pytest tests/unit/
+uv run pytest tests/integration/
+```
+
+Integration tests build real demo sites into `tests/demos/` — inspect them in your
+editor after a test run:
+
+```
+tests/demos/
+  mkdocs/       MkDocs default theme
+  material/     Material for MkDocs
+  zensical/     Zensical
+```
+
+### Linting and type checking
+
+```bash
+uv run ruff format mkdocs_treeview/ tests/ scripts/
+uv run ruff check mkdocs_treeview/ tests/ scripts/
+uv run mypy mkdocs_treeview/
+```
+
+Pre-commit hooks run these automatically before every commit:
+
+```bash
+uv run pre-commit install   # once, after cloning
+```
+
+### Update icons
+
+To update to a new version of `vscode-material-icon-theme`:
+
+```bash
+uv run python scripts/build_icons.py --version 5.x.y
+```
+
+Requires `npm` on PATH. Regenerates `mkdocs_treeview/icon_map.py` and
+`mkdocs_treeview/icons/`. Commit the result.
+
+---
+
+## Publishing
+
+### Build
+
+```bash
+uv build
+```
+
+Produces a wheel and sdist in `dist/`. Verify contents before publishing:
+
+```bash
+tar -tzf dist/*.tar.gz | sort
+unzip -l dist/*.whl
+```
+
+### Bump version
+
+Edit `version` in `pyproject.toml`, then tag the release:
+
+```bash
+git tag v0.2.0
+```
+
+### Publish to PyPI
+
+```bash
+UV_PUBLISH_TOKEN=pypi-... uv publish
+```
+
+---
+
+## Credits and license
+
+SVG icons from
+[vscode-material-icon-theme](https://github.com/material-extensions/vscode-material-icon-theme)
+by Philipp Kief and contributors — MIT license.
+
+Rendering approach inspired by
+[asciidoctor-treeview](https://github.com/lask79/asciidoctor-treeview)
+by lask79 — MIT license.
+
+This package is MIT licensed. See [LICENSE](LICENSE).

mkdocs_treeview-0.1.0/README.md

@@ -0,0 +1,291 @@
+# mkdocs-treeview
+
+A Python-Markdown extension and MkDocs plugin that renders ASCII file trees with
+[Material icon theme](https://github.com/material-extensions/vscode-material-icon-theme) icons.
+Works with MkDocs, Material for MkDocs, and Zensical.
+
+Inspired by [asciidoctor-treeview](https://github.com/lask79/asciidoctor-treeview).
+
+````markdown
+```treeview
+├── src/
+│   ├── main.py
+│   └── utils.py
+├── tests/
+│   └── test_main.py
+├── Dockerfile
+├── tsconfig.json
+└── README.md
+```
+````
+
+| Light | Dark |
+|:---:|:---:|
+| ![Treeview light theme](docs/images/treeview-light.png) | ![Treeview dark theme](docs/images/treeview-dark.png) |
+
+---
+
+## Features
+
+- Renders ` ```treeview ` fenced code blocks as styled file trees
+- Icons automatically chosen by file extension, file name, or folder name
+- Supports ASCII-tree format (`tree` command output) and symbol-based (`*`/`#`) format
+- Dynamic CSS — only icons actually used in your site are emitted (~7 KB instead of 1.3 MB)
+- Dark/light mode: separate light-variant icons for `[data-md-color-scheme="slate"]`
+- Three asset modes: `files` (local SVGs), `embedded` (base64 in CSS), `cdn` (jsDelivr)
+
+---
+
+## Installation
+
+```bash
+pip install mkdocs-treeview
+```
+
+---
+
+## Usage
+
+Write an ASCII tree in a fenced code block tagged `treeview`:
+
+````markdown
+```treeview
+├── src/
+│   ├── main.py
+│   └── utils.py
+├── tests/
+│   └── test_main.py
+├── Dockerfile
+├── tsconfig.json
+└── README.md
+```
+````
+
+Both formats are accepted:
+
+**ASCII-tree** (output of the `tree` command):
+```
+├── src/
+│   └── main.py
+└── README.md
+```
+
+**Symbol-based** (indent depth = number of markers):
+```
+* src/
+** main.py
+* README.md
+```
+
+---
+
+## Configuration
+
+### MkDocs (`mkdocs.yml`)
+
+```yaml
+plugins:
+  - treeview:
+      icon_mode: files   # files | embedded | cdn   (default: files)
+```
+
+The plugin registers the Markdown extension automatically and injects
+`assets/treeview/treeview.css` into `extra_css`. No other configuration needed.
+
+### Material for MkDocs (`mkdocs.yml`)
+
+Identical to the MkDocs configuration — the plugin works with any MkDocs theme:
+
+```yaml
+theme:
+  name: material
+
+plugins:
+  - treeview:
+      icon_mode: embedded
+```
+
+### Zensical (`zensical.toml`)
+
+Add the extension via `markdown_extensions` and point `extra_css` at the output file:
+
+```toml
+[project]
+extra_css = ["stylesheets/treeview.css"]
+
+[project.markdown_extensions."mkdocs_treeview.extension"]
+css_output_path = "docs/stylesheets/treeview.css"
+icon_mode = "embedded"
+```
+
+`css_output_path` is resolved relative to the directory where `zensical build` is
+run (the project root). The extension writes a lean CSS file there after each page.
+
+---
+
+## Asset modes
+
+| Mode | Behavior | Best for |
+|---|---|---|
+| `files` | SVGs copied to `assets/treeview/icons/`, CSS uses relative URLs | Production MkDocs sites |
+| `embedded` | SVGs inlined as base64 data URIs — single self-contained CSS file | Zensical, offline output |
+| `cdn` | CSS references jsDelivr URLs — no local files | Quick preview, GitHub rendering |
+
+---
+
+## How it works
+
+The MkDocs plugin hooks into `on_config` to register the Markdown extension and
+inject `extra_css`. During the build each page's treeview blocks are converted to
+HTML with `tv-icon tv-icon-<name>` CSS classes. After the build, `on_post_build`
+writes a lean CSS file containing only the icons that were actually rendered.
+
+For Zensical, `TreeviewCSSPostprocessor` writes the CSS file after every page.
+Because the extension object persists across all `render()` calls, the registry
+accumulates icons across pages. The final write contains the complete lean CSS.
+
+---
+
+## HTML output
+
+The renderer emits flat `<span class="tv-line">` rows with ASCII prefix connectors
+(matching the asciidoctor-treeview approach), rather than a nested `<ul>/<li>` tree:
+
+```html
+<div class="treeview">
+  <span class="tv-line">
+    <span class="tv-line-prefix">├──&nbsp;</span>
+    <span class="tv-line-element">
+      <i class="tv-icon tv-icon-folder-src-open"></i>
+      <span class="tv-item-name">src/</span>
+    </span>
+  </span>
+  <span class="tv-line">
+    <span class="tv-line-prefix">│&nbsp;&nbsp;&nbsp;├──&nbsp;</span>
+    <span class="tv-line-element">
+      <i class="tv-icon tv-icon-python"></i>
+      <span class="tv-item-name">main.py</span>
+    </span>
+  </span>
+  <span class="tv-line">
+    <span class="tv-line-prefix">│&nbsp;&nbsp;&nbsp;└──&nbsp;</span>
+    <span class="tv-line-element">
+      <i class="tv-icon tv-icon-python"></i>
+      <span class="tv-item-name">utils.py</span>
+    </span>
+  </span>
+  <span class="tv-line">
+    <span class="tv-line-prefix">└──&nbsp;</span>
+    <span class="tv-line-element">
+      <i class="tv-icon tv-icon-readme"></i>
+      <span class="tv-item-name">README.md</span>
+    </span>
+  </span>
+</div>
+```
+
+Folders with children use the open variant (`folder-src-open.svg`); leaf folders
+use the closed variant. Unknown file types fall back to a generic file icon.
+
+---
+
+## Development
+
+### Requirements
+
+- Python >= 3.9
+- [uv](https://docs.astral.sh/uv/) (recommended)
+- Node.js / npm (only for `scripts/build_icons.py` — regenerating the icon bundle)
+
+### Setup
+
+```bash
+uv sync
+```
+
+### Run tests
+
+```bash
+uv run pytest tests/unit/
+uv run pytest tests/integration/
+```
+
+Integration tests build real demo sites into `tests/demos/` — inspect them in your
+editor after a test run:
+
+```
+tests/demos/
+  mkdocs/       MkDocs default theme
+  material/     Material for MkDocs
+  zensical/     Zensical
+```
+
+### Linting and type checking
+
+```bash
+uv run ruff format mkdocs_treeview/ tests/ scripts/
+uv run ruff check mkdocs_treeview/ tests/ scripts/
+uv run mypy mkdocs_treeview/
+```
+
+Pre-commit hooks run these automatically before every commit:
+
+```bash
+uv run pre-commit install   # once, after cloning
+```
+
+### Update icons
+
+To update to a new version of `vscode-material-icon-theme`:
+
+```bash
+uv run python scripts/build_icons.py --version 5.x.y
+```
+
+Requires `npm` on PATH. Regenerates `mkdocs_treeview/icon_map.py` and
+`mkdocs_treeview/icons/`. Commit the result.
+
+---
+
+## Publishing
+
+### Build
+
+```bash
+uv build
+```
+
+Produces a wheel and sdist in `dist/`. Verify contents before publishing:
+
+```bash
+tar -tzf dist/*.tar.gz | sort
+unzip -l dist/*.whl
+```
+
+### Bump version
+
+Edit `version` in `pyproject.toml`, then tag the release:
+
+```bash
+git tag v0.2.0
+```
+
+### Publish to PyPI
+
+```bash
+UV_PUBLISH_TOKEN=pypi-... uv publish
+```
+
+---
+
+## Credits and license
+
+SVG icons from
+[vscode-material-icon-theme](https://github.com/material-extensions/vscode-material-icon-theme)
+by Philipp Kief and contributors — MIT license.
+
+Rendering approach inspired by
+[asciidoctor-treeview](https://github.com/lask79/asciidoctor-treeview)
+by lask79 — MIT license.
+
+This package is MIT licensed. See [LICENSE](LICENSE).