mkdocs-treeblocks 0.1.0__tar.gz

mkdocs_treeblocks-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python bytecode / caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Build / packaging output
+build/
+dist/
+*.egg-info/
+
+# Coverage
+.coverage
+htmlcov/
+
+# MkDocs output
+site/
+
+# OS/editor files
+.DS_Store
+.vscode/
+.idea/
+._.DS_Store
+
+# Test and local output artifacts
+*.log
+pytest.txt
+
+# Test and local output artifacts
+*.log
+pytest.txt

mkdocs_treeblocks-0.1.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# mkdocs-treeblocks 0.1.0
+
+## Initial alpha release of mkdocs-treeblocks.
+
+mkdocs-treeblocks is a MkDocs extension for rendering simple tree-style code blocks as directory/file tree output during a MkDocs build.
+
+Added
+
+* Added support for fenced ` ```tree` code blocks in Markdown.
+* Added parser support for indentation-based tree input.
+* Added Unicode tree rendering using branch characters such as ├── and └──.
+* Added Markdown transformation that converts source tree fences into rendered text fences.
+* Added MkDocs plugin integration through the treeblocks plugin entry point.
+* Added build-time diagnostics for invalid tree indentation.
+* Added diagnostics that report the source Markdown file and starting line of the failing tree block.
+* Added compatibility test coverage for both basic MkDocs and Material for MkDocs projects.
+* Added package metadata for local wheel and source distribution builds.
+---
+
+### Example Usage
+
+_Source Markdown:_
+
+```tree
+docs
+    index.md
+    guides
+        install.md
+```
+
+_Rendered output:_
+
+```text
+docs
+├── index.md
+└── guides
+    └── install.md
+```
+---
+
+## Installation
+
+`pip install mkdocs-treeblocks`
+
+Enable the plugin in mkdocs.yml:
+
+```yaml
+plugins:
+  - search
+  - treeblocks
+```
+---
+
+### Current limitations
+
+* Tree blocks currently use four-space or single tab indentation levels.
+* Error diagnostics report the source file and tree-block starting line, but not yet the exact malformed line inside the tree block.
+* This is an early alpha release, so syntax and behavior may still change before a stable 1.0.0 release.

mkdocs_treeblocks-0.1.0/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.

mkdocs_treeblocks-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,193 @@
+# 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.
+
+
+
+