Copy as Markdown Edit this page

On this page

Navigation

Configure header links, social icons, sidebar depth, and breadcrumbs.

4 min read

Header Navigation Links

Add links to your site header for quick access to key pages:

conf.py

html_theme_options = {
    "nav_links": [
        {"title": "Guide", "url": "getting-started"},
        {"title": "API", "url": "api/index"},
        {"title": "GitHub", "url": "https://github.com/you/your-project", "external": True},
    ],
}

Dropdown Menus

Create dropdown navigation menus with the children key:

conf.py

html_theme_options = {
    "nav_links": [
        {
            "title": "Reference",
            "children": [
                {"title": "Typography", "url": "reference/typography"},
                {"title": "Code Blocks", "url": "reference/code-blocks"},
            ],
        },
    ],
}

Social Links

Display icon links in the header (currently supports GitHub):

conf.py

html_theme_options = {
    "social_links": [
        {"icon": "github", "url": "https://github.com/you/your-project"},
    ],
}

Sidebar Depth

Control how deep the sidebar table of contents tree expands:

conf.py

html_theme_options = {
    "nav_depth": "4",   # Default: 4 levels deep
}

Collapsible Sidebar Items

Every branch in the left sidebar can be collapsed or expanded via a chevron toggle that appears next to its label. Behavior:

• The branch that contains the current page is auto-expanded on load, along with all of its ancestors. Readers always see where they are.

• Every other branch is expanded by default, but can be collapsed with a single click on its chevron.

• State is recomputed on each page load — it is not persisted across navigations.

Marking a branch collapsed by default

If a branch should start collapsed (until a reader visits a page inside it), add nav_collapsed: true to the frontmatter of its index page.

For MyST Markdown:

guides/advanced/index.md

---
nav_collapsed: true
---

# Advanced Topics

For reStructuredText, use a field list at the top of the document:

:nav_collapsed: true

Advanced Topics
===============

The branch auto-expands whenever the reader is viewing a page inside it, so collapsed-by-default entries never hide the current page.

Breadcrumbs

The breadcrumb trail above the content helps readers orient themselves. To hide it:

conf.py

html_theme_options = {
    "show_breadcrumbs": "false",
}

Page Table of Contents

The right-side page outline indents nested headings along a curved guide. An accent marker follows the current section as you scroll in either direction. It switches when a heading reaches the reading line below the fixed header; at the bottom of the page, it selects the final section. To hide it:

conf.py

html_theme_options = {
    "show_toc": "false",
}

Previous / Next Navigation

Page-level previous/next links appear at the bottom of each page. To hide them:

conf.py

html_theme_options = {
    "show_prev_next": "false",
}

Doc Sections

Group your documentation into distinct sections, each with its own icon, color, and sidebar navigation. A dropdown at the top of the sidebar lets readers switch between them — useful when your docs serve different audiences (e.g., users vs. developers) or cover separate products.

Setup

Define your sections in html_theme_options:

conf.py

html_theme_options = {
    "doc_sections": [
        {
            "name": "User Documentation",
            "description": "Installation, guides & reference",
            "icon": "book-open",
            "color": "#10b981",
            "default": True,
            "link": "getting-started/index",
        },
        {
            "path": "contributing",
            "name": "Developer Documentation",
            "description": "Architecture & development",
            "icon": "code",
            "color": "#8b5cf6",
        },
    ],
}

Each section has:

• name (required) – display name in the switcher dropdown

• description (required) – short tagline shown below the name

• icon (required) – a Lucide icon name (e.g., "book-open", "code")

• color (required) – hex color for the icon badge and section name in the switcher

• path or paths – directory prefixes that belong to this section. Use path for a single directory (e.g., "contributing"), or paths for multiple directories grouped under one section.

• default – set to True on one section to make it the catch-all. Any page not claimed by another section’s explicit paths automatically belongs to the default section.

• link – page to navigate to when clicking this section in the dropdown (e.g., "getting-started/index"). Defaults to the first entry in path/paths.

How It Works

When a reader visits a page that belongs to a section, the sidebar shows only that section’s navigation tree. The dropdown at the top highlights the active section and lets readers jump to any other section’s index page.

One section can be marked as "default": True. That section automatically includes every page not explicitly assigned to another section — you don’t need to list every directory. This is the simplest way to split docs into two groups like “User Documentation” (everything) and “Developer Documentation” (just contributing/).

These section names also appear in the Search in selector in Search. Search uses the same path matching and default section as the sidebar switcher.

Section colors are contained to the switcher dropdown — they don’t affect the rest of the page’s accent color.

Version Switcher

Display a dropdown in the header that lets readers switch between documentation versions. The version list loads from a JSON file you host alongside your docs.

Setup

1. Create a versions.json file and host it at a stable URL:

versions.json

[
  {"version": "latest", "url": "https://example.com/en/latest/", "name": "dev (latest)"},
  {"version": "1.17", "url": "https://example.com/en/1.17/"},
  {"version": "1.16", "url": "https://example.com/en/1.16/"}
]

Each entry has:

• version (required) – version identifier, used to match version_switcher_match

• url (required) – base URL for that version’s docs (must end with /)

• name (optional) – display label, falls back to version

2. Configure the theme in your conf.py:

conf.py

html_theme_options = {
    "version_switcher_json": "https://example.com/versions.json",
    "version_switcher_match": "1.17",
}

The version_switcher_match value should match a version field in your JSON. The dropdown highlights that entry as “(current)”.

How It Works

When a reader selects a different version, the switcher navigates to the same page path on the selected version’s URL. For example, viewing https://example.com/en/1.17/guides/search.html and selecting “latest” navigates to https://example.com/en/latest/guides/search.html.