---
title: "Navigation & Categories"
description: "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."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/guide/navigation"
---
# 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.

## What makes up navigation

| Location | Source |
| --- | --- |
| Header navigation (desktop) | `header.nav` in `app.config` |
| Mobile menu | `header.mobileNav`, falling back to `header.nav` when empty |
| Numbered section bar below the header (docs pages, desktop) | Top-level directories of `content/docs/` |
| Left sidebar | Pages in the current section, grouped by `docs.categories` and subdirectories |
| ⌘K search palette | Every docs page in the current language |

::u-color-mode-image{alt="Header navigation, section bar and sidebar" class="rounded-md border border-default" dark="/screenshots/navigation-overview-dark.png" light="/screenshots/navigation-overview-light.png"}
::

## Header navigation

```ts [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:

| Field | Type | Description |
| --- | --- | --- |
| `label` | `string \| Record<string, string>` | Text. An object is resolved by the current locale, falling back to the default locale and then the first value |
| `to` | `string` | Link target. Internal paths get the current locale prefix automatically, so `/docs` becomes `/en/docs` in English |
| `icon` | `string` | Icon shown in the mobile menu |
| `target` | `'_blank' \| '_self'` | Link target. External links (URLs with a protocol) default to `_blank` |
| `activeMatch` | `string` | Path prefix used for the active state, defaults to `to`. In the example, "Docs" is highlighted on every `/docs/**` page |
| `active` | `boolean` | Force 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`:

```yaml [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:

```text
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:

```md
---
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.

## Sidebar groups

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

```ts [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' }
      ]
    }
  }
})
```

```md [content/en/docs/2.guide/2.theme.md]
---
title: Theme & Fonts
category: basics
---
```

> [!WARNING]
> 
> 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.

## Sidebar filter

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:

```ts [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.

## Search

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.

::u-color-mode-image{alt="Recently viewed pages in the search palette" class="rounded-md border border-default" dark="/screenshots/search-recent-dark.png" light="/screenshots/search-recent-light.png"}
::

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.


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
