Sidebar navigation

Sidebar config applies to the docs collection. Path examples use site/ as the publish root from init.

Sidebar config is optional.

Without docs.sidebar, TidyPress builds the docs sidebar from published docs entries and their order frontmatter.

Use docs.sidebar only when you want explicit groups, custom ordering, or hidden pages.

For nested groups, links, separators, component nodes, and directory autogeneration, use the recursive navigation.sidebar tree. docs.sidebar remains the compact legacy form.

A recursive group may also set page so its heading links to an overview page. This is useful for a folder landing page with clearly grouped children.

Set expanded: true or expanded: false to make a group collapsible and choose its initial state. A group containing the current page opens automatically so the active location is never hidden. Omit expanded for an always-visible section.

Automatic Sidebar

This is enough for most projects:

---
title: Getting started
order: 1
---

TidyPress sorts docs pages by order, then by title/slug.

Explicit Groups

Use explicit groups when the docs need named sections:

docs: {
  sidebar: [
    {
      label: 'Getting started',
      items: ['why-tidypress', 'getting-started'],
    },
    {
      label: 'Configuration',
      items: ['configuration', 'display-options', 'i18n'],
    },
  ],
}

items are docs slugs relative to the docs collection root. For example:

site/src/content/docs/getting-started.md -> getting-started
site/src/content/docs/guides/install.md -> guides/install

Optional Group Labels

Group labels are optional:

docs: {
  sidebar: [
    {
      items: ['getting-started', 'configuration'],
    },
  ],
}

Use unlabeled groups when you only need ordering.

First Docs Page

The /docs route points to the first docs entry.

When docs.sidebar is configured, the first matching sidebar item wins. Otherwise, the first published docs entry by order wins.

Hidden Pages

With explicit groups, a page exists but does not appear in the sidebar unless its slug is listed.

Use this for landing pages, reference pages, or pages you only link to from another page.

Chapter Navigation

Docs pages use previous/next chapter navigation by default.

Control it globally:

docs: {
  paging: 'bottom',
}

Options:

Override one page:

---
title: Why TidyPress
paging: false
---

Chapter navigation follows the same ordering as the sidebar when explicit groups are configured.

Recursive Sidebar Tree

navigation: {
  sidebar: [
    {
      type: 'group',
      label: 'Runtime',
      page: 'runtime',
      expanded: true,
      children: [
        { type: 'page', page: 'architecture', icon: 'cpu', tag: 'core' },
        {
          type: 'group',
          label: 'Operations',
          children: [
            { type: 'page', page: 'operations/deploy' },
            { type: 'link', label: 'Status', href: 'https://status.example.com', external: true },
          ],
        },
        {
          type: 'group',
          label: 'Reference',
          page: 'reference',
          children: [{ type: 'autogenerated', directory: 'reference' }],
        },
      ],
    },
  ],
}

Project component nodes use { type: 'component', component: './src/components/SidebarStatus.astro' }.

In this example, reference.mdx is the linked group overview and files under reference/ become its children. Group page and autogenerated directory values are docs slugs relative to src/content/docs/; parent traversal is rejected. The outer group is a disclosure because it sets expanded; nested groups that omit the field remain visible.

Header Navigation

Use navigation.header for dropdowns, search/theme controls, project components, and explicit start/center/end placement:

navigation: {
  header: [
    { label: 'Docs', href: '/docs' },
    {
      type: 'dropdown',
      label: 'Resources',
      items: [{ label: 'API', href: '/docs/api' }],
    },
    { type: 'search', position: 'end' },
    { type: 'theme-toggle', position: 'end' },
  ],
},
navbar: {
  position: 'sticky',
  width: 'full',
  hideOnScroll: true,
}

See Presentation API for the complete node model.