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

↑ Docs content model

The :::docs-toc directive displays a table of contents built from a set of Markdown files and, optionally, the headings within them.

When to use

Use :::docs-toc on a landing or hub page to generate a navigable list of child pages instead of maintaining links by hand. Use Section table of contents instead when you want a TOC of the current page's own headings.

Technical details

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, specify which files are included via 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 optionally be 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.

The paths in both child directives can be either absolute (starting with a / and evaluated within docs/web/docs/) 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 (the default) lists only files, while depth=2 additionally lists each file's # headings.

Rules

• ::entry requires a file option; ::glob-entry requires a pattern option.
• Paths are absolute (evaluated within docs/web/docs/) or relative to the current file.
• depth defaults to 1 (files only).

Style

• Prefer automatic labels (from each page's title) so the TOC stays in sync when titles change; override with a manual label only when necessary.

Template

Markdown

:::docs-toc{depth=1}

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

:::

Examples

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='\*'}

:::

Used in

Content atoms appear in any page section. A docs TOC is most common on landing and hub pages that link out to a set of child pages.