Organize the table of contents

Add toc.md to a Markdown content root when the documentation needs stable navigation and publishing order. The root toc.md is not published as a topic. It describes the shape of the generated documentation for that Markdown content entry.

Create the root TOC

Place toc.md directly under the Markdown content root:

text 
docs/
|-- toc.md
|-- index.md
|-- installation.md
`-- guide/
    `-- usage.md

Use front matter to select the default topic:

markdown 
---
default_topic: index.md
---

default_topic selects the topic opened first by generated output that supports a default page. The path is resolved relative to the toc.md file. Set the content entry's display title with content.<name>.title in the project manifest. See Content.

Add navigation sections

Use H2 headings for top-level navigation groups and H3 headings for groups nested under the preceding H2. Use list items for the topics inside each group:

markdown 
## Get started

- [Overview](index.md)
- [Installation](installation.md)

## Guide

- [Usage](guide/usage.md)

Linked list items become pages in navigation. Plain list items become groups:

markdown 
## Guide

- Setup
  - [Installation](installation.md)
  - [Configuration](configuration.md)
- [Usage](guide/usage.md)

List indentation creates nested navigation. Keep nesting shallow enough that readers can scan the sidebar.

Use a linked heading when a navigation group also has a landing topic:

markdown 
## [Command-line tools](cli/index.md)

### Basics

- [Install](cli/install.md)

### [Advanced](cli/advanced.md)

- [Configuration](cli/configuration.md)

The heading title becomes the navigation group title. The heading link becomes the group target.

TOC topic links use normal relative Markdown paths:

markdown 
- [Installation](installation.md)
- [Usage](guide/usage.md)

Paths in a root toc.md are resolved relative to the Markdown content root. Paths in a nested toc.md are resolved relative to that nested toc.md file.

TOC links must point to topics inside the same Markdown content entry. Use a cross-reference when a topic needs to point at generated content from another content entry.

Split large navigation

Use a nested toc.md when one area has its own navigation:

text 
docs/
|-- toc.md
`-- guide/
    |-- toc.md
    |-- installation.md
    `-- usage.md

Link to the directory from the parent TOC:

markdown 
## Documentation

- [Overview](index.md)
- [Guide](guide/)

The linked directory must contain its own toc.md:

markdown 
# Guide

- [Installation](installation.md)
- [Usage](usage.md)

DocInsight replaces the directory link with the nested TOC group. The nested TOC's H1 becomes the group title.

Understand publishing order

When a Markdown content root has toc.md, DocInsight uses it as the primary publishing shape. Topics linked from the TOC are published and appear in navigation.

DocInsight also keeps:

  • The root index.md landing page when it exists.

  • The configured default_topic.

  • Markdown topics reached through links from already published topics.

When a Markdown content root does not have toc.md, DocInsight still discovers Markdown topics selected by root, files, and exclude, then generates automatic navigation from the topic paths.