Docs table of contents (`:::docs-toc`)

We support the following syntax for displaying a table of contents based on the docs content structure:

Markdown
:::docs-toc{depth=<optional-tree-depth>}

::entry{file='<file-name>'}

::entry[<optional-label>]{file='<file-name>'}

::glob-entry{pattern='<glob-pattern>'}

:::

The displayed table of contents (TOC) is based on the set of Markdown files specified in it, optionally along with the hierarchies of Markdown headings in those files. Inside the docs-toc container directive, you can specify which files will be included via the following two types of child directives:

The entry directive includes the single Markdown file specified by the file option. By default, it receives an automatic label based on its page title, which can be optionally overridden by specifying a manual label in square brackets.
The glob-entry directive includes all Markdown files matching the glob pattern specified by the pattern option.

info

The paths specified in both types of child directives can be either absolute (starting with a / and evaluated within the docs/web/docs/ directory) or relative to the current file.

Specifying a depth caps the nesting depth of files and headings included in the TOC. For example, depth=1 (which is the default) causes the TOC to only list files, while depth=2 causes it to additionally list each file's # headings.

Example:

Markdown
Docs Table of Contents with default titles

:::docs-toc{depth=1}

::entry{file='admonitions.md'}

::entry{file='/internal/directives/clouds.md'}

:::

Docs Table of Contents with explicit titles

:::docs-toc{depth=1}

::entry[Admonitions]{file='admonitions.md'}

::entry[Clouds]{file='/internal/directives/clouds.md'}

:::

Docs Table of Contents with glob

:::docs-toc{depth=1}

::glob-entry{pattern='\*'}

:::

Docs Table of Contents with deeper `depth`

:::docs-toc{depth=2}

::glob-entry{pattern='\*'}

:::

Output:

Docs Table of Contents with default titles

Docs Table of Contents with explicit titles

Docs Table of Contents with glob

Docs Table of Contents with deeper depth