Navigation and Sidebar

Sarde auto-generates sidebar navigation from the directory structure in docs-layout collections. Pages are sorted by sidebar.order (from frontmatter or numeric filename prefix), then by title. No configuration is required for the default behavior.

Auto-generated sidebar

For docs-layout collections (docs/, courses/, tutorials/, etc.), Sarde walks the directory tree and builds a collapsible navigation sidebar. Each subdirectory with an _index.md becomes a collapsible group. Pages within a group are sorted by their sidebar.order field.

content/docs/
  _index.md
  start-here/                    # Sidebar group: "Start Here"
    _index.md                    # sidebar.order: 1
    getting-started.md
    deploying.md
  guides/                        # Sidebar group: "Guides"
    _index.md                    # sidebar.order: 2
    writing-content.md

Result: The sidebar shows two collapsible groups with pages nested inside each.

Controlling sidebar order

Set sidebar.order in frontmatter to control the position of a page or section within its parent group:

---
title: Getting Started
sidebar:
  order: 1
---

Alternatively, prefix filenames with numbers: 01-getting-started.md sets sidebar.order to 1 without frontmatter. See Writing Content for details.

Sidebar labels

Override the sidebar display label without changing the page title:

---
title: Internationalization and Localization
sidebar:
  label: "i18n"
---

Result: The sidebar shows "i18n" while the page heading remains "Internationalization and Localization".

Hiding pages

Hide a page from the sidebar while keeping it accessible via direct URL:

---
title: Internal Notes
sidebar:
  hidden: true
---

Sidebar badges

Add a badge chip next to a sidebar item:

---
title: New Feature
sidebar:
  badge: "New"
---

Badges also support variant styling:

---
sidebar:
  badge:
    text: "Beta"
    variant: "caution"
---

Collapsible sections

Sidebar groups are collapsible by default. Configure this per collection in sarde.yaml:

collections:
  docs:
    sidebar:
      collapsible: true
      collapsed_by_default: false
      max_depth: 4

Open/closed state for each group persists across page navigations via sessionStorage.

Manual tab sidebar with nav.yaml

Tabbed collections can use nav.yaml inside a tab
directory to replace the auto-generated navigation for that tab. Use this when
the tab needs links that do not match the file tree.

The file only applies per tab. A nav.yaml at the collection root is ignored,
and non-tabbed collections always use the auto-generated sidebar.

content/docs/guides/nav.yaml

- label: "Getting Started"
  page: getting-started
- label: "Guides"
  items:
    - label: "Writing Content"
      page: guides/writing-content
    - label: "Code Blocks"
      page: guides/code-blocks
- label: "External Docs"
  url: "https://example.com"
  external: true

Each item supports:

Items without page or url act as group labels (headings with no link).

Breadcrumbs

Docs-layout pages render breadcrumbs automatically: Collection Root > Section > Page. Transparent sections are skipped in the breadcrumb trail. Sections without an _index.md appear as plain text (no link).

Prev/next links

Docs-layout collections render prev/next navigation links at the bottom of each page. The order follows a depth-first traversal of the sidebar tree, so readers navigate through sections sequentially.

Override prev/next for a specific page in frontmatter:

---
prev: "installation"
next:
  slug: "advanced-config"
  label: "Advanced Configuration"
---

Disable prev/next for a page:

---
prev: false
next: false
---

Global navigation

The site header displays navigation links configured in sarde.yaml:

header:
  links:
    - label: "Docs"
      url: "/docs/"
    - label: "Blog"
      url: "/blog/"
    - label: "GitHub"
      url: "https://github.com/getsarde/sarde"
      external: true

Header links appear as a horizontal navigation bar. External links open in a new tab.

Table of contents

Docs-layout pages display a table of contents panel on the right side of the content area. The TOC lists headings extracted from the page content, with scroll-synchronized highlighting of the current section.

Disable the TOC site-wide or per collection:

toc:
  enabled: false

Or per page in frontmatter:

---
toc: false
---

Heading level range

Two settings control which headings appear in the TOC:

1. markdown.toc.min_heading_level / max_heading_level controls which headings are extracted during the build. Headings outside this range get no id attribute, no anchor link, and cannot be linked to with fragment URLs. Default: 2 through 4.

2. toc.min_level / toc.max_level controls which extracted headings are displayed in the TOC sidebar. This can only narrow the range, not widen it beyond what was extracted. Default: 2 through 4.

To include all heading levels in the TOC:

markdown:
  toc:
    max_heading_level: 6
toc:
  max_level: 6

To extract h2 through h6 for IDs and link validation, but only display h2 and h3 in the sidebar:

markdown:
  toc:
    max_heading_level: 6
toc:
  max_level: 3

Per-page frontmatter can override the display range for individual pages. See Frontmatter for per-page toc: options.

Mobile sidebar

On screens narrower than 1024px, the sidebar collapses into a drawer accessible via a hamburger menu button. The drawer slides in from the left and contains the same navigation tree. It closes on link click or by tapping outside the drawer.

See Configuration for all sidebar settings, and Frontmatter for per-page sidebar fields.