Navigation & Categories

Header links, the mobile menu and sidebar groups are declared in app.config, while the docs directory structure drives the section bar and the sidebar order. This page covers where each navigation comes from, localized labels and link prefixes, sidebar grouping rules, the sidebar filter and ⌘K search.
View source

What makes up navigation

LocationSource
Header navigation (desktop)header.nav in app.config
Mobile menuheader.mobileNav, falling back to header.nav when empty
Numbered section bar below the header (docs pages, desktop)Top-level directories of content/docs/
Left sidebarPages in the current section, grouped by docs.categories and subdirectories
⌘K search paletteEvery docs page in the current language
Header navigation, section bar and sidebar

Header navigation

app/app.config.ts
export default defineAppConfig({
  header: {
    nav: [
      { label: { 'zh-CN': '文档', 'en': 'Docs' }, to: '/docs/getting-started', activeMatch: '/docs' },
      { label: { 'zh-CN': '版本发布', 'en': 'Releases' }, to: '/releases' },
      { label: 'GitHub', to: 'https://github.com/my/repo' }
    ],
    mobileNav: [
      { label: { 'zh-CN': '快速开始', 'en': 'Get Started' }, icon: 'i-lucide-square-play', to: '/docs/getting-started' },
      { label: { 'zh-CN': '版本发布', 'en': 'Releases' }, icon: 'i-lucide-newspaper', to: '/releases' }
    ]
  }
})

Each link accepts:

FieldTypeDescription
labelstring | Record<string, string>Text. An object is resolved by the current locale, falling back to the default locale and then the first value
tostringLink target. Internal paths get the current locale prefix automatically, so /docs becomes /en/docs in English
iconstringIcon shown in the mobile menu
target'_blank' | '_self'Link target. External links (URLs with a protocol) default to _blank
activeMatchstringPath prefix used for the active state, defaults to to. In the example, "Docs" is highlighted on every /docs/** page
activebooleanForce the active state, overriding prefix matching

Icon buttons on the right of the header come from header.links; when a GitHub repository is configured, a GitHub icon is prepended automatically.

Section bar

Docs pages show a numbered section bar below the header. Each item is a top-level directory of content/docs/, titled by that directory's .navigation.yml:

content/docs/2.guide/.navigation.yml
title: Guide
icon: i-lucide-compass

When the directory has an index.md, the section bar links to the directory itself (such as /docs/getting-started); otherwise it links straight to the first page of the section, with no redirect to configure. The LandingIndex contents list on landing pages follows the same rule.

Ordering

Numeric prefixes on directories and files set the order and never appear in routes:

content/docs/
├── 1.getting-started/
│   ├── .navigation.yml
│   ├── 1.index.md          → /docs/getting-started
│   └── 2.installation.md   → /docs/getting-started/installation
└── 2.guide/
    ├── .navigation.yml
    ├── 1.configuration.md  → /docs/guide/configuration
    └── 10.faq.md           → /docs/guide/faq

Page frontmatter adjusts how a single page appears in navigation:

---
title: Configuration Overview
navigation:
  title: Configuration   # shorter title in the sidebar
  badge: New             # badge next to the title
---

Set navigation: false to hide a page from the sidebar and section lists; the page remains reachable.

The sidebar only shows pages in the current section, grouped in this order:

  1. Overview: pages with neither a subdirectory nor a category
  2. Subdirectories: each subdirectory in the section becomes a group, titled by its .navigation.yml
  3. Categories: pages whose frontmatter category matches a category declared in docs.categories, in declaration order
app/app.config.ts
export default defineAppConfig({
  docs: {
    categories: {
      // Keys are section directory slugs without the numeric prefix
      guide: [
        { id: 'basics', title: { 'zh-CN': '基础', 'en': 'Basics' }, icon: 'i-lucide-settings' },
        { id: 'customization', title: { 'zh-CN': '定制', 'en': 'Customization' }, icon: 'i-lucide-paintbrush' }
      ]
    }
  }
})
content/en/docs/2.guide/2.theme.md
---
title: Theme & Fonts
category: basics
---
When a category matches no id in the current section's docs.categories, the page falls back to the Overview group and a warning is logged during development so you can declare it.

Sections with many pages can show a filter at the top of the sidebar. It matches navigation titles and descriptions and is cleared on navigation:

app/app.config.ts
export default defineAppConfig({
  aside: {
    filter: {
      enabled: true,
      threshold: 10,
      shortcut: '/'
    }
  }
})

The filter only appears once the current section has at least threshold items. shortcut focuses the filter; set it to an empty string to disable it.

The header search box and ⌘K (Ctrl+K on Windows and Linux) open the search palette. It indexes every docs page in the current language, matched by page title and heading sections. Set header.search: false to hide the search entry.

Recently viewed pages in the search palette

With an empty query, the palette lists the last 6 docs pages visited in the current language. The history is stored in the visitor's localStorage and never sent to the server.

Copyright © 2024 - 2026