Navigation

The top navigation bar provides quick access to major documentation areas. zpress supports automatic generation or explicit configuration.

Auto navigation

Set nav: 'auto' (the default) to generate one nav item per non-isolated top-level section:

export default defineConfig({
  sections: [
    {
      text: 'Getting Started',
      icon: 'pixelarticons:speed-fast',
      link: '/getting-started',
      from: 'docs/getting-started.md',
    },
    {
      text: 'Guides',
      icon: 'pixelarticons:book-open',
      prefix: '/guides',
      from: 'docs/guides/*.md',
    },
    {
      text: 'Reference',
      icon: 'pixelarticons:list-box',
      prefix: '/reference',
      from: 'docs/reference/*.md',
    },
  ],
  nav: 'auto',
})

This produces three nav items: Getting Started, Guides, and Reference. Sections with isolated: true are excluded from auto-generated nav.

Explicit navigation

Pass an array of NavItem objects for full control:

export default defineConfig({
  sections: [
    { text: 'Guides', prefix: '/guides', from: 'docs/guides/*.md' },
    { text: 'Reference', prefix: '/reference', from: 'docs/reference/*.md' },
  ],
  nav: [
    { text: 'Guides', link: '/guides/sections-and-pages' },
    { text: 'Reference', link: '/reference/configuration' },
  ],
})

Nav items with items instead of link render as dropdown menus:

nav: [
  {
    text: 'API',
    items: [
      { text: 'REST API', link: '/api/rest' },
      { text: 'GraphQL', link: '/api/graphql' },
    ],
  },
]

Isolated sections as dropdowns

Sections marked isolated: true get their own sidebar namespace. In auto nav mode, isolated sections are excluded from the main nav items. Use explicit nav if you want isolated sections represented as dropdowns.

Active state

In auto mode, nav items highlight based on the current URL matching the section's link or prefix. For explicit nav, use activeMatch to control highlighting:

{ text: 'API', link: '/api/overview', activeMatch: '/api/' }

The activeMatch value is a regex pattern tested against the current URL path.

References