Documentation set navigation

Documentation set navigation defines how files within a single documentation set are organized and structured. Each documentation set is responsible for its own internal navigation hierarchy.

Documentation set navigation allows repository maintainers to:

• Organize content: Define the logical structure of their documentation.
• Control hierarchy: Determine which pages are nested under others.
• Create sections: Group related content together.
• Maintain autonomy: Structure documentation independently of other repositories.

Navigation is defined in the toc (table of contents) section of the docset.yml file:

toc:
  - file: index.md
  - folder: contribute
    children:
      - file: index.md
      - file: locally.md
        children:
          - file: page.md
		

The toc section supports several node types:

Reference a single markdown file:

- file: getting-started.md
		

Files can also have nested children:

- file: locally.md
  children:
    - file: page.md
		

Group related files together:

- folder: configuration
  children:
    - file: index.md
    - file: basic.md
		

children is optional for folder nodes. This will include all files in the folder. This is especially useful during development when you are unsure how to structure your documentation.

Once children is defined, it must reference all .md files in the folder. The build will fail if it detects any dangling documentation files.

Hide pages from navigation while keeping them accessible:

- hidden: deprecated-page.md
		

For larger documentation sets, create named TOC sections that can be referenced in global navigation:

toc:
  - file: index.md
  - toc: development
		

This will include the toc section defined in development/toc.yml:`

When a toc section becomes too unwieldy, folders can define a dedicated toc.yml file to organize their files and link them in their parent toc.yml or docset.yml file.

In your docset.yml:

toc:
  - file: index.md
  - folder: contribute
    children:
      - file: index.md
      - file: locally.md
        children:
          - file: page.md
  - toc: development
		

Then create development/toc.yml:

toc:
  - file: index.md
  - toc: link-validation
		

• Modularity: Each section can be maintained independently.
• Cleaner docset.yml: Keep the main file focused and readable.
• Easier refactoring: Rename folders without updating TOC references.
• Team ownership: Different teams can manage different TOC sections.

All file paths in the toc section are relative to the documentation set root (where docset.yml is located):

toc:
  - file: index.md                    # docs/index.md
  - folder: api
    children:
      - file: index.md                # docs/api/index.md
      - file: authentication.md       # docs/api/authentication.md
		

You can customize how items appear in the navigation:

The navigation title defaults to a markdown's page first h1 heading.

To present the file differently in the navigation, add a navigation_title metadata field.

---
title: Getting Started with the Documentation Builder
navigation_title: Quick Start
---
		

There is no way to set title in the docset.yml file. This is by design to keep a page's data contained in its file.

When building assembled documentation, the documentation set navigation becomes a component of the global navigation:

• Documentation set navigation defines the structure within a repository.
• Global navigation defines how repositories are organized relative to each other.

Named toc sections in docset.yml can be referenced and reorganized in the global navigation.yml file without affecting the documentation set's internal structure.

Understanding the different ways to structure navigation helps you choose the right pattern for your documentation. Each pattern serves a specific purpose and has its own trade-offs.

The simplest pattern - just reference individual markdown files:

toc:
  - file: index.md
  - file: getting-started.md
  - file: faq.md
		

When to use: For flat documentation with few pages or when pages don't naturally group together.

Advantages: Simple and explicit. No hidden files or automatic inclusion.

Considerations: Doesn't scale well for large documentation sets.

Group related files under a parent without creating a physical folder structure:

toc:
  - file: getting-started.md
    children:
      - file: installation.md
      - file: configuration.md
      - file: first-steps.md
		

When to use: When you want to create a logical grouping without reorganizing files on disk, typically for sibling files in the same directory.

Advantages: Creates navigation hierarchy without changing the file system. Useful for grouping related pages that share a parent.

Considerations: Children must be siblings of the parent file. The parent can't select files from different directories. Avoid deep-linking (using paths with / in the file reference when it has children) - the builder will emit hints suggesting you use folder structures instead.

Example scenario: You have several setup guides at the root level that you want to group under a "Getting Started" parent page:

docs/
├── getting-started.md
├── installation.md
├── configuration.md
└── first-steps.md
		

Let the builder automatically include all markdown files in a folder:

toc:
  - folder: tutorials
  - folder: api
		

When to use: During active development when content is still evolving, or for folders where file order doesn't matter.

Advantages: Zero maintenance - new files are automatically included. Perfect for development.

Considerations: No control over file order. All markdown files in the folder will be included.

Define exactly which files appear and in what order:

toc:
  - folder: api
    children:
      - file: index.md
      - file: authentication.md
      - file: endpoints.md
      - file: errors.md
		

When to use: When file order matters or when you need precise control over what's included.

Advantages: Complete control over structure and ordering. The builder validates that all files are accounted for.

Considerations: Requires maintenance. The builder will error if files exist in the folder that aren't listed in children.

Combine a folder reference with a specific entry file:

toc:
  - folder: getting-started
    file: getting-started.md
    children:
      - file: prerequisites.md
      - file: installation.md
		

When to use: When you want a folder with a main overview file that's not named index.md.

Advantages: Clear entry point. Works well when the folder name and overview file name match.

Considerations: The builder will hint if the file name doesn't match the folder name (unless you use index.md). This pattern works best when names align:

Good examples:

# File name matches folder name
- folder: getting-started
  file: getting-started.md

# Using index.md always works
- folder: api-reference
  file: index.md
		

Triggers hints:

# File name doesn't match folder name
- folder: getting-started
  file: overview.md
		

1. Hint: Consider naming this getting-started.md

Split large documentation into separate toc.yml files:

In docset.yml:

toc:
  - file: index.md
  - toc: getting-started
  - toc: api-reference
  - toc: guides
		

In getting-started/toc.yml:

toc:
  - file: index.md
  - file: installation.md
  - file: configuration.md
		

When to use: For large documentation sets, when different teams own different sections, or when you want to keep docset.yml focused and readable.

Advantages: Modularity. Each section can evolve independently. Easier folder renames (the folder name isn't repeated in its own toc.yml). Better for team ownership.

Considerations: toc.yml files can't nest other toc.yml files - only docset.yml can reference them.

Example scenario: You're building product documentation with multiple major sections:

docs/
├── docset.yml
├── index.md
├── getting-started/
│   ├── toc.yml
│   └── ...
├── api-reference/
│   ├── toc.yml
│   └── ...
└── guides/
    ├── toc.yml
    └── ...
		

In practice, you'll combine patterns based on your needs:

toc:
  - file: index.md
  - file: quick-start.md
  - folder: tutorials
  - folder: api
    children:
      - file: index.md
      - file: authentication.md
  - toc: guides
		

1. Single file
2. Single file
3. Auto-include during development
4. Explicit control for stability
5. Large section in separate file

As you build navigation, the docs-builder may emit hints suggesting improvements to your structure. These hints help maintain best practices but can be suppressed when you have valid reasons to deviate.

Add a suppress section to either docset.yml or toc.yml:

suppress:
  - DeepLinkingVirtualFile
  - FolderFileNameMismatch

toc:
  - file: index.md
  # ... rest of your navigation
		

What it detects: Files with children that use paths containing /:

toc:
  - file: guides/advanced/performance.md
    children:
      - file: guides/advanced/caching.md
      - file: guides/advanced/optimization.md
		

Why it hints: Virtual files (files with children) work best for grouping sibling files together. Using deep paths suggests you might benefit from proper folder structures.

When to suppress: Rarely. This usually indicates a structural issue. Consider refactoring to use folders or nested toc files instead.

Better alternative:

toc:
  - folder: guides
    children:
      - folder: advanced
        children:
          - file: index.md
          - file: performance.md
            children:
              - file: caching.md
              - file: optimization.md
		

What it detects: Folder and file combinations where names don't match:

toc:
  - folder: getting-started
    file: overview.md
		

1. Doesn't match folder name

Why it hints: Matching names create predictable, consistent navigation. When a folder is named "getting-started," readers expect the main file to be either getting-started.md or index.md.

When to suppress: When you have legacy documentation with established naming conventions, or when the file name is intentionally different for clarity.

Better alternatives:

# Option 1: Match the names
- folder: getting-started
  file: getting-started.md

# Option 2: Use index.md (conventional and always appropriate)
- folder: getting-started
  file: index.md

# Option 3: Just use folder with children
- folder: getting-started
  children:
    - file: index.md
    - file: prerequisites.md
		

Suppressions are escape hatches, not defaults. Use them when:

• Migrating legacy content: Existing documentation has established patterns that can't be changed immediately
• Valid architectural reasons: Your specific use case genuinely benefits from the flagged pattern
• Temporary transitions: You're in the middle of restructuring and need to suppress hints during the migration

Example of justified suppression:

# This section uses an established URL structure we can't change
# without breaking external links. Suppressing the hint until we
# can implement proper redirects.
suppress:
  - FolderFileNameMismatch

toc:
  - folder: install
    file: setup.md  # External links point to /install/setup
    children:
      - file: prerequisites.md
		

• Group related content in folders that reflect logical sections
• Use descriptive names - folder and file names become URLs
• Maintain hierarchy - think about how users navigate from general to specific

The folder names and hierarchy translate directly to URL structure. folder: api/authentication becomes /docs/api/authentication/ in the browser.

Begin with automatic folder inclusion during development:

toc:
  - file: index.md
  - folder: guides
  - folder: api
		

1. Auto-includes everything
2. Auto-includes everything

As content stabilizes, add explicit children for control:

toc:
  - file: index.md
  - folder: guides
    children:
      - file: index.md
      - file: getting-started.md
      - file: advanced-topics.md
  - toc: api
		

1. Now you control the order
2. Extract to separate toc.yml

Every folder should have an index.md that introduces the section:

- folder: api
  children:
    - file: index.md
    - file: authentication.md
    - file: endpoints.md
		

1. Overview of the API section

The index file provides context before users dive into specific topics. It's also what users see when they navigate to /docs/api/.

Deep navigation hierarchies overwhelm readers. Aim for three to four levels maximum:

Good (3 levels):

Documentation
  └── Guides
      └── Installation
          └── Prerequisites
		

Too deep (6 levels):

Documentation
  └── Guides
      └── Getting Started
          └── Installation
              └── Linux
                  └── Ubuntu
                      └── Prerequisites
		

If you need more depth, consider splitting into separate documentation sets or using virtual file grouping for minor subdivisions.

When a section grows beyond 5-10 files or has its own internal structure, move it to a dedicated toc.yml:

docs/
├── docset.yml
├── index.md
└── api-reference/
    ├── toc.yml
    ├── index.md
    └── ...
		

1. High-level structure only
2. API section structure

Benefits:

• Keeps docset.yml focused on top-level organization
• Teams can own their section's navigation
• Easier to refactor individual sections
• Folder renames don't require updating the toc.yml (since the folder name isn't repeated inside it)

TOC section names become part of URLs and navigation structure:

Good (clear and descriptive):

- toc: api-reference
- toc: getting-started
- toc: troubleshooting
- toc: user-guide
		

Bad (vague and uninformative):

- toc: section1
- toc: misc
- toc: other
- toc: stuff
		

Choose names that:

• Describe the content clearly
• Work well in URLs (lowercase, hyphenated)
• Match user expectations

• Global Navigation - How documentation sets are organized in assembled documentation.
• Content Set Configuration - Complete docset.yml reference.
• Navigation Configuration - Detailed navigation options.