Header Navigation

Configure header navigation tabs with optional nested dropdown menus

zudo-doc supports a navigation hierarchy inspired by Docusaurus:

• Header nav — top-level tabs in the site header, with optional dropdown menus
• Sidebar categories — collapsible groups in the sidebar
• Sidebar items — individual pages within categories

Configuration

Define header navigation items in src/config/settings.ts. Items can be flat links or dropdown parents with nested children:

export const settings = {
  // ...
  headerNav: [
    // Flat link (no dropdown)
    { label: "Getting Started", labelKey: "nav.gettingStarted", path: "/docs/getting-started", categoryMatch: "getting-started" },

    // Dropdown parent with children
    {
      label: "Learn",
      labelKey: "nav.learn",
      path: "/docs/guides",
      categoryMatch: "guides",
      children: [
        { label: "Guides", labelKey: "nav.guides", path: "/docs/guides", categoryMatch: "guides" },
        { label: "Components", labelKey: "nav.components", path: "/docs/components", categoryMatch: "components" },
      ],
    },

    { label: "Reference", labelKey: "nav.reference", path: "/docs/reference", categoryMatch: "reference" },
  ],
};

Properties

HeaderNavItem

HeaderNavChildItem

Child items use the same properties as HeaderNavItem except they cannot have their own children. This enforces a single level of nesting at the type level.

labelKey

The labelKey property enables localized header navigation labels. When set, zudo-doc looks up the key in the current locale’s translation file and uses the translated string instead of label. If no translation is found, label is used as a fallback.

Translation keys follow the nav.* namespace convention (e.g., "nav.gettingStarted", "nav.guides").

categoryMatch

The categoryMatch property connects a header tab to a specific sidebar category. When a header tab with categoryMatch is active, the sidebar filters to show only the pages within that category.

For example, categoryMatch: "guides" links the tab to the guides/ content directory. When a user navigates to any page under /docs/guides/, the “Guides” tab becomes active and the sidebar shows only the guides category.

Children can also have categoryMatch. For example, placing categoryMatch: "components" on a child ensures that visiting /docs/components/ activates the parent dropdown and filters the sidebar to the components section.

Dropdown Behavior

Items with children render as dropdown menus. The parent item itself remains a clickable link — clicking it navigates to its path. The dropdown provides quick access to related sub-pages.

• Desktop: opens on hover and closes when the mouse leaves the menu area. A small chevron indicates the dropdown.
• Keyboard: opens when the trigger receives focus (via focus-within). Press Escape to close. Fully accessible without a mouse.
• Mobile: nested items appear as expandable groups in the mobile sidebar menu, with a toggle chevron to expand/collapse children.
• Overflow: when the browser window is narrow and a dropdown parent is moved to the overflow ”…” menu, its children are shown as indented sub-items.

Active State

A header nav item is considered active when the current page URL starts with the item’s path. If the current page matches any child item’s path, the parent item also shows as active.

For example, visiting /docs/components/admonitions activates the “Learn” dropdown because /docs/components matches one of its children.

Mobile Behavior

On small screens (< 1024px), the desktop header nav is hidden. The sidebar toggle provides access to all navigation on mobile. Nested navigation items appear as expandable groups in the mobile sidebar — tap the chevron to expand/collapse children.