mkdocs-treeblocks 0.1.0__py3-none-any.whl

mkdocs_treeblocks/__init__.py

@@ -0,0 +1 @@
+"""Tree block support for MkDocs."""

mkdocs_treeblocks/parser.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+class TreeParseError(ValueError):
+    """Raised when tree block text cannot be parsed."""
+
+
+@dataclass
+class TreeNode:
+    text: str
+    children: list["TreeNode"] = field(default_factory=list)
+
+
+def parse_tree(text: str) -> TreeNode:
+    """Parse indented tree block text into a TreeNode hierarchy."""
+    parsed_lines = _parse_lines(text)
+
+    if not parsed_lines:
+        raise TreeParseError("Tree block is empty.")
+
+    root_depth, root_text = parsed_lines[0]
+
+    if root_depth != 0:
+        raise TreeParseError("The first tree node must not be indented.")
+
+    root = TreeNode(root_text)
+    stack: list[tuple[int, TreeNode]] = [(root_depth, root)]
+
+    for depth, node_text in parsed_lines[1:]:
+        if depth > stack[-1][0] + 1:
+            raise TreeParseError("Tree indentation cannot skip levels.")
+
+        while stack and stack[-1][0] >= depth:
+            stack.pop()
+
+        if not stack:
+            raise TreeParseError("Tree contains more than one root node.")
+
+        node = TreeNode(node_text)
+        stack[-1][1].children.append(node)
+        stack.append((depth, node))
+
+    return root
+
+
+def _parse_lines(text: str) -> list[tuple[int, str]]:
+    indent_style: str | None = None
+    parsed_lines: list[tuple[int, str]] = []
+
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+
+        indent, node_text = _split_indent(line)
+
+        if indent:
+            line_indent_style = _detect_indent_style(indent)
+
+            if indent_style is None:
+                indent_style = line_indent_style
+            elif indent_style != line_indent_style:
+                raise TreeParseError("Tree block cannot mix tabs and spaces for indentation.")
+
+            depth = _indent_depth(indent, line_indent_style)
+        else:
+            depth = 0
+
+        parsed_lines.append((depth, node_text))
+
+    return parsed_lines
+
+
+def _split_indent(line: str) -> tuple[str, str]:
+    stripped = line.lstrip(" \t")
+    indent_length = len(line) - len(stripped)
+    return line[:indent_length], stripped
+
+
+def _detect_indent_style(indent: str) -> str:
+    has_spaces = " " in indent
+    has_tabs = "\t" in indent
+
+    if has_spaces and has_tabs:
+        raise TreeParseError("Tree block cannot mix tabs and spaces for indentation.")
+
+    if has_tabs:
+        return "tabs"
+
+    return "spaces"
+
+
+def _indent_depth(indent: str, indent_style: str) -> int:
+    if indent_style == "tabs":
+        return len(indent)
+
+    if len(indent) % 4 != 0:
+        raise TreeParseError("Space indentation must use multiples of four spaces.")
+
+    return len(indent) // 4

mkdocs_treeblocks/plugin.py

@@ -0,0 +1,30 @@
+"""MkDocs plugin integration for mkdocs-treeblocks."""
+
+from __future__ import annotations
+
+from mkdocs.exceptions import PluginError
+from mkdocs.plugins import BasePlugin
+
+from mkdocs_treeblocks.parser import TreeParseError
+from mkdocs_treeblocks.transform import transform_markdown
+
+
+class TreeblocksPlugin(BasePlugin):
+    """MkDocs plugin that transforms fenced tree blocks before Markdown rendering."""
+
+    def on_page_markdown(self, markdown: str, **kwargs: object) -> str:
+        """Transform tree blocks in a page's Markdown source."""
+        try:
+            return transform_markdown(markdown)
+        except TreeParseError as error:
+            page = kwargs.get("page")
+            page_file = getattr(page, "file", None)
+            source_path = getattr(page_file, "src_path", None)
+
+            if source_path:
+                message = f"treeblocks failed in {source_path}: {error}"
+            else:
+                message = f"treeblocks failed: {error}"
+
+            raise PluginError(message) from error
+            

mkdocs_treeblocks/renderer.py

@@ -0,0 +1,38 @@
+from mkdocs_treeblocks.parser import TreeNode
+
+
+def render_tree(root: TreeNode) -> str:
+    """Render a parsed tree as plain text using Unicode tree connectors."""
+    lines = [root.text]
+
+    for index, child in enumerate(root.children):
+        is_last = index == len(root.children) - 1
+        _render_child(
+            child,
+            lines,
+            prefix="",
+            is_last=is_last,
+        )
+
+    return "\n".join(lines)
+
+
+def _render_child(
+    node: TreeNode,
+    lines: list[str],
+    *,
+    prefix: str,
+    is_last: bool,
+) -> None:
+    connector = "└── " if is_last else "├── "
+    lines.append(f"{prefix}{connector}{node.text}")
+
+    child_prefix = f"{prefix}{'    ' if is_last else '│   '}"
+
+    for index, child in enumerate(node.children):
+        _render_child(
+            child,
+            lines,
+            prefix=child_prefix,
+            is_last=index == len(node.children) - 1,
+        )

mkdocs_treeblocks/transform.py

@@ -0,0 +1,54 @@
+"""Markdown transformation helpers for mkdocs-treeblocks."""
+
+from __future__ import annotations
+
+import re
+
+from mkdocs_treeblocks.parser import TreeParseError, parse_tree
+from mkdocs_treeblocks.renderer import render_tree
+
+
+_TREE_FENCE_RE = re.compile(
+    r"(?P<opening>^```tree[ \t]*\n)"
+    r"(?P<body>.*?)"
+    r"(?P<closing>^```[ \t]*$)",
+    re.MULTILINE | re.DOTALL,
+)
+
+
+def transform_markdown(markdown: str) -> str:
+    """Transform fenced tree blocks into rendered fenced text blocks.
+
+    The source block:
+
+        ```tree
+        docs
+            index.md
+        ```
+
+    becomes:
+
+        ```text
+        docs/
+        └── index.md
+        ```
+
+    Non-tree fenced code blocks are left unchanged.
+    """
+
+    def replace_tree_block(match: re.Match[str]) -> str:
+        tree_source = match.group("body")
+        block_line = markdown.count("\n", 0, match.start()) + 1
+
+        try:
+            root_nodes = parse_tree(tree_source)
+        except TreeParseError as error:
+            raise TreeParseError(
+                f"tree block starting at line {block_line}: {error}"
+            ) from error
+
+        rendered_tree = render_tree(root_nodes)
+
+        return f"```text\n{rendered_tree}\n```"
+
+    return _TREE_FENCE_RE.sub(replace_tree_block, markdown)

mkdocs_treeblocks-0.1.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: mkdocs-treeblocks
+Version: 0.1.0
+Summary: A MkDocs extension for rendering tree-style code blocks and directory structures.
+Author: Joshua Mullenberg
+License: MIT License
+        
+        Copyright (c) [2026] [Joshua Mullenberg]
+        
+        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 WITHOUT LIMITATION 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.md
+Keywords: directory-structure,documentation,markdown,mkdocs,tree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: MkDocs
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: markdown>=3.6
+Requires-Dist: mkdocs>=1.6
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mkdocs-treeblocks
+_Revised on: 06-13-2026 by: Joshua Mullenberg_
+
+`mkdocs-treeblocks` is a MkDocs plugin for rendering readable tree-style blocks in documentation.
+
+The goal is to make directory structures, file trees, project layouts, and related hierarchy examples easier to write, read, and maintain in MkDocs documentation.
+
+> [!NOTE]
+> This project is currently in development. Syntax, behavior, and package interfaces are still subject to change.
+
+## Initial purpose
+
+This project grew from a need to create clean, text-based tree-style blocks directly in documentation using simple Markdown syntax.
+
+The goal is to avoid switching to a separate app, copying output from a web tool, manually inserting Unicode tree characters, or wrestling with tree command filters just to produce a curated directory structure for documentation.
+
+mkdocs-treeblocks provides a small, predictable syntax that renders tree structures consistently in MkDocs sites.
+
+## Syntax
+
+Tree blocks are written as fenced Markdown code blocks. Use three backticks (` ``` `) to open and close the block, with `tree` as the language identifier.
+
+The plugin converts the indentation into a tree structure, and then formats that structure into a fenced text-block using Unicode tree connectors.
+
+Indentation may use either four spaces or one tab per level, but cannot use both indentation styles within the same tree block. Text and spacing after the structural indentation are preserved, allowing filenames, comments, and annotations to remain aligned.
+
+Only one root node is allowed per tree block.
+
+<table>
+    <tr>
+        <th>Syntax by example</th>
+        <th>Rendered output</th>
+    </tr>
+    <tr>
+        <td>
+            <pre><code>
+```tree
+mkdocs-project/
+    docs/
+        index.md
+        ...
+    mkdocs.yml        # mkdocs config
+    README.md
+    requirements.txt  # dependencies
+    site/
+        404.html
+        assets/
+        index.html
+        ...
+```
+            </code></pre>
+        </td>
+        <td>
+            <pre><code>
+```text
+mkdocs-project/
+├── docs/
+│   ├── index.md
+│   └── ...
+├── mkdocs.yml        # mkdocs config
+├── README.md
+├── requirements.txt  # dependencies
+└── site/
+    ├── 404.html
+    ├── assets/
+    ├── index.html
+    └── ...
+```
+            </code></pre>
+        </td>
+    </tr>
+</table>
+
+---
+
+## Installation, testing, and usage
+
+Clone the repository, create and activate a virtual environment, then install the project in editable mode with its development dependencies:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+The editable install registers the treeblocks plugin with MkDocs and allows local source changes to take effect without reinstalling the package.
+
+Run the test suite:
+
+```bash
+python -m pytest
+```
+
+Enable the plugin in mkdocs.yml:
+
+```yaml
+plugins:
+  - treeblocks
+```
+
+Then write a fenced tree block in a Markdown page:
+
+````
+```tree
+docs/
+    index.md
+    guides/
+        install.md
+```
+````
+
+During the MkDocs build, the plugin transforms the source into a fenced text block containing the rendered tree.
+
+---
+## Current implementation status
+
+Implemented:
+
+- Parse indented text into a tree structure with `parse_tree()`.
+- Render a parsed tree as plain text with `render_tree()`.
+- Use Unicode tree connectors such as `├──`, `└──`, and `│`.
+- Preserve original node text, including aligned comments and annotations.
+- Transform fenced Markdown `tree` blocks into rendered fenced `text` blocks with `transform_markdown()`.
+- Leave non-`tree` fenced code blocks unchanged.
+- Integrate with MkDocs through the `treeblocks` plugin.
+- Raise MkDocs `PluginError` for invalid tree blocks.
+- Include the source file and tree-block starting line in MkDocs parse errors when page context is available.
+- Test parser, renderer, Markdown transformer, MkDocs plugin behavior, and Material for MkDocs compatibility with `pytest`.
+- Material for Mkdocs compatibility testing.
+
+Potential future enhancements:
+
+- Error messages include exact malformed line inside the tree block.
+- Custom HTML rendering.
+- Dedicated CSS styling.
+- Optional automatic directory slash handling.
+
+---
+## Project Roadmap
+
+#### <s>Phase 1: Scaffold and concept</s>
+- <s>Create the project</s>
+- <s>Set up the GitHub repository</s>
+- <s>Document the purpose and syntax</s>
+- <s>Add placeholder tests</s>
+- <s>Create the initial README</s>
+- <s>Make the first commit</s>
+ 
+#### <s>Phase 2: Parser MVP</s>
+- <s>Choose the first supported syntax</s>
+- <s>Parse a small indented tree</s>
+- <s>Add parser tests</s>
+- <s>Add incremental documentation in /docs/</s>
+
+#### <s>Phase 3: Renderer MVP</s>
+- <s>Define renderer MVP behavior</s>
+- <s>Add renderer tests</s>
+- <s>Implement a plain Python renderer</s>
+- <s>Document renderer behavior</s>
+ 
+#### <s>Phase 4: Markdown transform MVP</s>
+- <s>Choose fenced `tree` blocks as the first supported Markdown source syntax</s>
+- <s>Detect and transform tree blocks in Markdown</s>
+- <s>Replace transformed tree blocks with fenced `text` blocks</s>
+- <s>Keep the transformer independent from MkDocs integration</s>
+
+#### </s>Phase 5: MkDocs plugin MVP</s>
+- <s>Add a minimal MkDocs plugin</s>
+- <s>Register the plugin with MkDocs</s>
+- <s>Add a minimal MkDocs fixture.</s>
+- <s>Add MkDocs integration tests.</s>
+- <s>Wrap parser failures as MkDocs `PluginError`</s>
+
+#### <s>Phase 6: Error handling & testing</s>
+- <s>Add source file and tree-block starting line diagnostics for parse errors.</s>
+- <s>Test with Material for MkDocs.</s>
+
+#### Phase 7: Publish initial release
+- Finalize package metadata in `pyproject.toml`.
+- Install build tooling and create distribution packages.
+- Test the built wheel in a clean virtual environment
+- Publish the release to PyPI
+
+#### Phase 8: Documentation Polish
+- Update current documentation.
+- Verify documentation includes installation, usage, and examples.
+- Document limitations and troubleshooting notes.
+- Set up GitHub issue and feature-request tracking.
+
+
+
+

mkdocs_treeblocks-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mkdocs_treeblocks/__init__.py,sha256=r8eHWhFTpL4M3lcba_HyM67OZ_4Tz2-2GXh1zIexCAg,37
+mkdocs_treeblocks/parser.py,sha256=3ZC_GUpGqABoqthYMSUrbbhY1y3jpwrdOZuDEf4W6UA,2679
+mkdocs_treeblocks/plugin.py,sha256=saO1lODV5ofi9mQ_vBm2MY6mjTY5oBjbdxA8uYAvbUE,1039
+mkdocs_treeblocks/renderer.py,sha256=R6m6UaJZD4g9SyGjFgxZUiHTce17Z3Q1rYnzpT8czd8,940
+mkdocs_treeblocks/transform.py,sha256=uk7T1EUO4CB-Cr9SOx6qaNsgWWV38GEuxiq3wEynTmQ,1280
+mkdocs_treeblocks-0.1.0.dist-info/METADATA,sha256=CHdoYP5TjWaG5r2HkmdPSN2H01j2OUhWv7WFaTMKHpw,8428
+mkdocs_treeblocks-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mkdocs_treeblocks-0.1.0.dist-info/entry_points.txt,sha256=YqYCqZeMF-toHM7cVnEslaJ0QGOgGUostWEfe0Lifv8,72
+mkdocs_treeblocks-0.1.0.dist-info/licenses/LICENSE.md,sha256=DA7SnOsKY-fPaE3w7WZ--yEDWFo5gC4sVoSKuwWqlkY,1078
+mkdocs_treeblocks-0.1.0.dist-info/RECORD,,

mkdocs_treeblocks-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mkdocs_treeblocks-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+treeblocks = mkdocs_treeblocks.plugin:TreeblocksPlugin

mkdocs_treeblocks-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Joshua Mullenberg]
+
+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 WITHOUT LIMITATION 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.