# 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.

## Link a navigation group

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.

## Link to topics

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.