<!--
Sitemap:
- [What is Vocs](/introduction/what-is-vocs): Learn why Vocs exists and when to use it
- [Getting Started](/introduction/getting-started): Install Vocs and create your first documentation site
- [Project Structure](/introduction/project-structure): Overview of the structure of a Vocs project
- [Writing Docs with AI](/introduction/writing-docs-with-ai): Use an AI agent to create and maintain Vocs documentation
- [Markdown Extensions](/writing/markdown-extensions): Features and syntax of Markdown in Vocs
- [Code & Syntax Highlighting](/writing/syntax-highlighting): Rich markup and annotations for code
- [Twoslash](/writing/twoslash): Add type-aware annotations to code examples
- [Code Snippets](/writing/code-snippets): Include and reuse code in Markdown
- [Markdown Snippets](/writing/markdown-snippets): Include other Markdown files in MDX
- [React in Markdown](/writing/react): Compose MDX pages with React components
- [Mermaid Diagrams](/writing/mermaid): Render diagrams from text using Mermaid
- [Assets](/writing/assets): Manage images, fonts, icons, and other docs assets
- [Frontmatter](/writing/frontmatter): Configure page metadata, layouts, search, and UI visibility
- [Navigation](/features/navigation): Keep docs navigation synced with routes
- [Search](/features/search): Built-in client-side search powered by MiniSearch
- [Layouts](/features/layouts): Choose and customize page shells for your docs
- [Slots](/features/slots): Inject custom components into the docs shell
- [Theming](/features/theming): Customize colors, typography, spacing, logos, and code themes
- [Tailwind CSS](/features/tailwind): Use Tailwind utilities in Vocs pages and components
- [Dynamic OG Images](/features/dynamic-og-images): Generate social preview images from page metadata
- [Page Feedback](/features/feedback): Collect page-level feedback from readers
- [Redirects](/features/redirects): Preserve old URLs and route legacy paths to new locations
- [API Routes](/features/api-routes): Add server-rendered endpoints to your docs site
- [Agent Support](/features/agent-support): Serve documentation in machine-readable form for AI agents
- [Ask AI](/features/ask-ai): Built-in AI assistant menu on every page
- [MCP Server](/features/mcp-server): Expose your docs and source code to AI assistants
- [Changelog Generation](/features/changelog-generation): Fetch release notes and render a changelog page
- [Site Configuration](/reference/site-config): Reference for options accepted by defineConfig
- [Frontmatter Reference](/reference/frontmatter): All frontmatter fields accepted by a Vocs MDX page
- [Components](/reference/components): Reference for the public React components exported from Vocs
- [Hooks](/reference/hooks): Reference for the React hooks exported from Vocs
- [Changelog](/changelog): Release history for Vocs
-->

# Navigation \[Keep docs navigation synced with routes]

Vocs reads pages from `src/pages`, but your visible navigation lives in `vocs.config.ts`. When you add, move, or rename pages, update navigation in the same change.

## Quick Prompt

Ask your AI agent to read this guide before changing navigation:

```txt
Read https://vocs.dev/features/navigation and update the sidebar/top navigation for the docs pages in this project.
```

## Overview

Configure both navigation surfaces in `vocs.config.ts`:

* `sidebar` controls the docs navigation.
* `topNav` controls links and menus in the top bar.

The `pages/` directory defines your routes. The `vocs.config.ts` file defines what readers and agents can discover.

## Recipes

### Adding Pages

When you create `src/pages/guide/install.mdx`, add the matching route to `sidebar`.

```ts [vocs.config.ts]
import { defineConfig } from 'vocs/config'

export default defineConfig({
  sidebar: [
    { text: 'Getting Started', link: '/introduction/getting-started' },
    { text: 'Installation', link: '/guide/install' },
  ],
})
```

### Adding Sections

Group related pages with an item that has `items`.

```ts [vocs.config.ts]
import { defineConfig } from 'vocs/config'

export default defineConfig({
  sidebar: [
    { text: 'Getting Started', link: '/introduction/getting-started' },
    {
      text: 'Writing',
      collapsed: false,
      items: [
        { text: 'Code & Syntax Highlighting', link: '/writing/syntax-highlighting' },
        { text: 'Code Snippets', link: '/writing/code-snippets' },
        { text: 'Markdown Snippets', link: '/writing/markdown-snippets' },
        { text: 'Markdown Extensions', link: '/writing/markdown-extensions' },
        { text: 'Using React', link: '/writing/react' },
      ],
    },
  ],
})
```

### Moving Pages

When you move a page file, update the old sidebar link to the new route and add a redirect from the old URL.

```diff [vocs.config.ts]
export default defineConfig({
+  redirects: [
+    { source: '/guide/install', destination: '/introduction/getting-started/install' },
+  ],
  sidebar: [
-   { text: 'Installation', link: '/guide/install' },
+   { text: 'Installation', link: '/introduction/getting-started/install' },
  ],
})
```

:::tip
Use [`redirects`](/reference/site-config#redirects) to preserve old links when pages move.
:::

### Scoping Sidebars

Use the object form when different route sections need different sidebars.

```ts [vocs.config.ts]
import { defineConfig } from 'vocs/config'

export default defineConfig({
  sidebar: {
    '/guide': [
      { text: 'Getting Started', link: '/introduction/getting-started' },
      { text: 'Theming', link: '/features/theming' },
    ],
    '/reference': {
      backLink: true,
      items: [
        { text: 'Site Config', link: '/reference/site-config' },
        { text: 'Components', link: '/reference/components' },
      ],
    },
  },
})
```

Vocs picks the deepest matching path prefix for the current page.

### Highlighting Top Nav

Use `match` when one top nav item should stay active across a broader section.

```ts [vocs.config.ts]
import { defineConfig } from 'vocs/config'

export default defineConfig({
  topNav: [
    {
      text: 'Guide & API',
      link: '/introduction/getting-started',
      match: (path) => Boolean(path?.startsWith('/guide') || path?.startsWith('/reference')),
    },
  ],
})
```

`match` can be either:

* a string prefix like `'/guide'`
* a function like `(path) => path?.startsWith('/guide')`

### Adding External Links

Absolute URLs are treated as external automatically. Set `external: true` when you want to be explicit.

```ts [vocs.config.ts]
import { defineConfig } from 'vocs/config'

export default defineConfig({
  sidebar: [
    {
      text: 'GitHub',
      link: 'https://github.com/wevm/vocs',
      external: true,
    },
  ],
  topNav: [
    {
      text: 'Resources',
      items: [
        { text: 'Changelog', link: '/changelog' },
        { text: 'GitHub', link: 'https://github.com/wevm/vocs' },
      ],
    },
  ],
})
```

## Reference

:::note
See the [Site Config reference](/reference/site-config#sidebar) for the full `sidebar` API.
:::

### Sidebar Fields

Each sidebar item can use these fields:

* `text`
* `link`
* `items`
* `collapsed`
* `disabled`
* `external`

### `backLink`

Set `backLink: true` to show a `Back` link at the top of a path-scoped sidebar section.

```ts [vocs.config.ts]
import { defineConfig } from 'vocs/config'

export default defineConfig({
  sidebar: {
    '/reference': {
      backLink: true,
      items: [{ text: 'Site Config', link: '/reference/site-config' }],
    },
  },
})
```