mkdocs-treeblocks 0.1.0

A MkDocs extension for rendering tree-style code blocks and directory structures.

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.

Syntax by example	Rendered output
```tree mkdocs-project/ docs/ index.md ... mkdocs.yml # mkdocs config README.md requirements.txt # dependencies site/ 404.html assets/ index.html ... ```	```text mkdocs-project/ ├── docs/ │ ├── index.md │ └── ... ├── mkdocs.yml # mkdocs config ├── README.md ├── requirements.txt # dependencies └── site/ ├── 404.html ├── assets/ ├── index.html └── ... ```

---

Installation, testing, and usage

Clone the repository, create and activate a virtual environment, then install the project in editable mode with its development dependencies:

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:

python -m pytest

Enable the plugin in mkdocs.yml:

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

Phase 1: Scaffold and concept

• Create the project
• Set up the GitHub repository
• Document the purpose and syntax
• Add placeholder tests
• Create the initial README
• Make the first commit

Phase 2: Parser MVP

• Choose the first supported syntax
• Parse a small indented tree
• Add parser tests
• Add incremental documentation in /docs/

Phase 3: Renderer MVP

• Define renderer MVP behavior
• Add renderer tests
• Implement a plain Python renderer
• Document renderer behavior

Phase 4: Markdown transform MVP

• Choose fenced tree blocks as the first supported Markdown source syntax
• Detect and transform tree blocks in Markdown
• Replace transformed tree blocks with fenced text blocks
• Keep the transformer independent from MkDocs integration

Phase 5: MkDocs plugin MVP

• Add a minimal MkDocs plugin
• Register the plugin with MkDocs
• Add a minimal MkDocs fixture.
• Add MkDocs integration tests.
• Wrap parser failures as MkDocs PluginError

Phase 6: Error handling & testing

• Add source file and tree-block starting line diagnostics for parse errors.
• Test with Material for MkDocs.

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.