Site Navigation

Last updated Oct 12, 2026100% grounded

Overview

Introduction

Site Navigation helps structure your documentation by organizing pages into sidebars, breadcrumbs, tables of contents, and multi-folder hierarchies. It transforms your content structure into a navigable tree so users can effortlessly find their way around your project.

The navigation system provides cohesive tools for managing your documentation layout:

Multi-Folder Hierarchies: Group related topics using nested folders and metadata configuration files.
Page Sidebars: Render your page tree into a collapsible, interactive menu with active state tracking.
Breadcrumb Trails: Display hierarchical path links so users know their exact location.
Tables of Contents: Extract page headings into a sidebar or mobile popover for quick section jumping.

Organizing Multi-Folder Hierarchies

Folder Structures

You can structure content into deep, multi-folder hierarchies using folders and metadata configuration files. Folders can contain index pages, sub-folders, and individual content pages, allowing you to group related topics together.

Key Concepts

Page Tree: The hierarchical model that represents your site's structure, composed of folders, pages, and separators.
Metadata Configuration: Optional files placed inside folders to customize folder titles, icons, descriptions, sorting behavior, and root nesting.

Tip

You can set a folder as a root navigation boundary by defining root properties in your folder metadata. This isolates the sidebar and breadcrumbs to that specific section.

Structuring Page Sidebars

Sidebar Layouts

The sidebar renders the site's page tree as a collapsible menu with nested folders, links, and separators.

Configuring Sidebar Behavior

You can control how folders behave in the sidebar using various options:

Default Open Level: Automatically expand folders up to a specified depth level when the page loads.
Collapsible Folders: Allow users to expand or collapse folder contents.
Active Highlighting: Visually highlight the currently active page or folder path in the sidebar.

Note

On mobile viewports, the sidebar automatically transforms into an accessible drawer overlay that can be toggled using the sidebar button.

Breadcrumbs display the current page's location within the site hierarchy, helping users understand their depth and navigate back to parent folders.

Configuring Breadcrumbs

Breadcrumb paths are automatically generated based on the current page's position in the page tree. You can customize what appears in the breadcrumb trail using the following options:

Option	Description	Default Value
`includeRoot`	Include root folders in the breadcrumb items array.	`false`
`includePage`	Include the current page itself in the breadcrumb items array.	`false`
`includeSeparator`	Count separator nodes as items in the breadcrumb list.	`false`

Tip

You can pass custom URLs or configure root overrides if you want the breadcrumb root to point to a specific destination rather than the default tree root.

Page Outlines

The Table of Contents (TOC) extracts headings from the current page and displays them in a sidebar or a mobile popover, allowing users to jump directly to specific sections.

TOC Styles and Popovers

Normal Style: Displays the table of contents as a sticky sidebar on wider desktop viewports.
Clerk Style: An alternative visual style for listing table of contents items.
TOC Popover: On smaller screens where sidebars are hidden, the TOC collapses into an interactive popover trigger showing progress and heading titles.

Warning

If a page contains no headings and no custom header or footer content is provided, the table of contents container will remain hidden.

Was this page helpful?

Search Configuration

Customizing Layouts