Directory Trees

The idea behind this plugin was inspired by this ASCII tree generator.

Creating a Markdown-It Plugin

The documentation for developers looking to create a Markdown-It plugin are woefully inadequate. Thus, most of this plugin was written based on the implementations of other plugins, such as the Vitepress Mermaid plugin and Vitepress Code snippet plugin.

It basically works by detecting when a code block has been assigned the dirtree language, parses the code block's content as YAML and converts that object into the directory structure that can then be rendered as text.

To create your own directory tree, use the dirtree language with your markdown code block:

``` dirtree

```

Within the dirtree code block, YAML is used for configuring the output. Start by first configuring your root object:

``` dirtree
name: root directory
```

If you do not specify a name for your root directory, then it will have the default name of "root". Now you can proceed to create children elements using a YAML list:

``` dirtree
name: root directory
children:
  - item0
  - name: item1
    children:
      - item2
```

Each item can either just be a string entry (like item0 above), in which case that entry is simply displayed as is, or it can be a compound YAML object like item1 is. The details for such an entry are as follows:

name: item1  # You must provide the name property
comment: This is an optional comment
children:    # Optional list of items
  - item2

Optional Comments

If provided, the comment is rendered on the same line, in alignment with all other comments:

root
├── item1                           // This is a comment
├── item2                           // Notice how all comments are
│   └── item3                       // aligned at the end
└── this_item_has_a_very_long_name

Path Validation

In the case you intend for your displayed directory tree to reflect the structure of an actual directory on disk, you can specify a path property on the root object. This path is resolved from the file containing the markdown.

<!-- Located in docs/index.md -->
``` dirtree
name: root directory
path: ./root   # gets resolved to docs/root
children:
  - item0
  - name: item1
    children:
      - item2
```

The plugin will then traverse down the directory structure. For each item, if it has children, it checks that the item corresponds to a directory of the same name on disk. In the example above, the plugin would check that docs/root was a folder that contained either a file or directory called item0.

It would also check that docs/root/item1 exists and that is is a directory (since it has children elements). This check is recursively performed on each subdirectory.

WARNING

This validation is only performed for items that have been specified in the dirtree, i.e. it doesn't consider items that are present on disk but aren't listed as an issue.

If the check fails a warning will be printed to the console stating which files it wasn't able to locate.

Path validation is optional; Not providing a path means that no validation is performed, so dirtrees can reflect arbitrary directory structures.

Highlighting

Each level of nesting is given its own colour retrieved from the Github set of colours. Code highlighting in Vitepress is powered by shiki. After the initial YML gets parsed and transformed into the raw uncoloured directory tree, the rendered code block gets passed to a code transformer, which parses the directory tree according to its own Textmate Grammar. Then, colours are applied to each line.

The grammar and code transformer are also exported from the Markdown Tree plugin and are applied in the Vitepress configuration. Refer to the codeTransformers and languages under the markdown set of options.

Do note that directory trees are intended to reflect actual structures within an actual file system. Therefore, if you use names for items that aren't valid as file names you might get incorrect highlighting.