Skip to content

Directory trees

prodockit.tree turns an indented list of folders and files into a directory tree. Use it to show readers where files belong in a project.

Enable the extension

[project.markdown_extensions."prodockit.tree"]

Write a tree

/// tree
docs/ - the documentation source tree
  index.md - the home page
  stylesheets/ - style sheets for the website and PDF
    extra.css - website style sheet
    print.css - PDF style sheet
zensical.toml - project configuration
///
  • docsthe documentation source tree
    • index.mdthe home page
    • stylesheetsstyle sheets for the website and PDF
      • extra.csswebsite style sheet
      • print.cssPDF style sheet
  • zensical.tomlproject configuration

The complete block starts and ends with a three-slash fence. Its body follows three rules:

  • Indentation is the structure. Two spaces per level by default.
  • A trailing / means a directory. Anything else is a file. Nothing else marks one, so nothing else can disagree with it.
  • - starts a description, and it is optional. The spaces are required, which is what keeps harvard-cite-them-right.csl in one piece.

Configure indentation and icons

There are no additional prodockit.tree settings in zensical.toml. Configure each tree inside its Markdown block. Put the options directly below /// tree, indent them by at least four spaces, and leave a blank line before the listing:

Option Default What it does
indent 2 How many spaces one level costs. Set 4 for a listing written that way.
directory_icon ':lucide-folder:' Icon shortcode placed before every directory.
file_icon ':lucide-file:' Icon shortcode placed before every file.

This example changes both the indentation and the icons:

/// tree
    indent: 4
    directory_icon: ':octicons-file-directory-16:'
    file_icon: ':octicons-file-16:'

docs/
    index.md
///
  • docs
    • index.md

Fix indentation errors

A listing is read for its shape, so an entry attached to the wrong parent is a diagram that is wrong and looks right. Rather than guess, the build stops:

TreeError: indent of 3 is not a multiple of 2: 'index.md'
TreeError: indented 2 levels at once: 'index.md'

A report project

Use the block for a structure readers need to understand. This example shows the main files supplied by prodockit-template:

  • docs
    • index.mdcover page
    • section1.mdfirst report section
    • acronyms.mdacronym definitions
    • glossary.mdglossary definitions
    • references.mdgenerated reference list
    • stylesheets
      • extra.csswebsite style sheet
      • print.cssPDF style sheet
  • tools
    • mermaiddiagram renderer
    • mathjaxmaths renderer
  • zensical.tomlnavigation and extension configuration
  • references.bibbibliography source

The package's own source-code map now lives under Contributor internals.

Reference

Syntax or option Purpose
/// tree Open or close a directory tree
A trailing / Mark an entry as a directory
- description Add an optional description
indent: 4 Use four spaces for each level instead of two
directory_icon: '…' Choose the directory icon
file_icon: '…' Choose the file icon
attrs: {...} Add an id, class, or other attribute to the tree

The tree block follows the same fence, option, and nesting rules as PyMdown Blocks.

Customise the appearance

The extension adds stable class names that you can target in your project's CSS style sheet. This repository's docs/stylesheets/extra.css contains the styles used by the examples on this page.

Generated HTML

The extension provides structure; your project supplies the appearance:

<div class="prodockit-tree">
  <ul>
    <li class="tree-directory">
      <span class="tree-icon">…</span>
      <span class="tree-name">docs</span>
      <span class="tree-note">the documentation source tree</span>
      <ul>
        <li class="tree-file">
          <span class="tree-icon">…</span>
          <span class="tree-name">index.md</span>
        </li>
      </ul>
    </li>
  </ul>
</div>

Stable class names include .prodockit-tree, .tree-directory, .tree-file, .tree-icon, .tree-name, and .tree-note.

docs/stylesheets/extra.css in this repository carries a CSS style sheet to start from. Keep the rail and stub positioned from one shared measurement, so changing indentation cannot pull them apart, and stop the last child's rail at its own stub rather than continuing past the final entry.