Docs Navigation

docsNav defines the documentation information architecture. Each top-level docs nav section becomes a docs subnav item, and its items define the sidebar shown for that section.

Keep intentional documentation sites explicit: list the pages in the order they should appear. Use autogenerate only when a section should follow the file tree automatically.

Dahlia chooses the navigation shell automatically. When docsNav has at least two top-level sections and every top-level section has an icon, Dahlia shows those sections in a select-style subNav. Otherwise, it omits subNav and combines the top-level sections into one sidebar. This keeps small documentation sites compact while preserving section switching for larger sites.

{
  "docsNav": [
    {
      "slug": "guide",
      "label": "Guides",
      "icon": "lucide:rocket",
      "items": [
        "overview",
        "installation",
        {
          "label": "Configuration",
          "items": [
            "configuration/project",
            "configuration/content-routing",
            "configuration/i18n",
            "configuration/appearance"
          ]
        },
        "deployment"
      ]
    },
    {
      "label": "Components",
      "icon": "lucide:blocks",
      "items": [
        "components/icon",
        "components/badge",
        "components/callout"
      ]
    }
  ]
}

You can also pass the same structure to dahlia({...}) in astro.config.ts:

docsNav: [
  {
    slug: 'guide',
    label: 'Guides',
    icon: 'lucide:rocket',
    items: [
      'overview',
      'installation',
      {
        label: 'Configuration',
        items: [
          'configuration/project',
          'configuration/content-routing',
          'configuration/i18n',
          'configuration/appearance',
        ],
      },
      'deployment',
    ],
  },
  {
    label: 'Components',
    icon: 'lucide:blocks',
    items: ['components/icon', 'components/badge', 'components/callout'],
  },
]

Sections

Top-level docs nav objects support label, optional slug, optional icon, optional translations, and items.

{
  slug: 'guide',
  label: 'Guides',
  translations: {
    'zh-cn': '指南',
  },
  icon: 'lucide:rocket',
  items: [],
}

slug is optional. If omitted, Dahlia derives it from the label. Add a slug when the visible label and stable section id should differ.

String Items

String items reference content collection entry IDs. With the default docsLoader() base, those IDs are relative to src/content/docs.

items: ['overview', 'installation', 'deployment']

'installation' resolves to src/content/docs/installation.mdx in a monolingual site, or to the current locale’s installation.mdx in an i18n site. For this example site, root English content lives in src/content/docs/en/, but the sidebar still references it as installation.

Link Items

Use link items for internal or external links that are not generated from docs content. Link items support icons and badges for status labels, API methods, or other compact metadata.

{
  label: 'GitHub',
  link: 'https://github.com/prosefly/astro-theme-dahlia',
  external: true,
  icon: 'simple-icons:github',
}

Use a trailing badge for status labels such as beta or new.

{
  label: 'Webhooks',
  link: 'references/webhooks',
  badge: {
    label: 'Beta',
    color: 'warning',
    variant: 'soft',
  },
}

Use a leading badge for API endpoints where the badge is part of the scanned label.

{
  label: '/users',
  link: 'api/users',
  badge: {
    label: 'GET',
    position: 'leading',
    color: 'success',
    variant: 'soft',
  },
}

String badges render as trailing neutral badges.

{
  label: 'Search',
  link: 'configuration/search',
  badge: 'New',
}

Badges support position: 'leading' | 'trailing', variant: 'solid' | 'soft' | 'subtle' | 'outline', and color: 'neutral' | 'accent' | 'info' | 'success' | 'warning' | 'danger'.

Groups

Groups create nested sidebar sections. They can be collapsed by default.

{
  label: 'Getting Started',
  translations: {
    'zh-cn': '入门',
  },
  items: [
    'overview',
      'installation',
      {
        label: 'Configuration',
        collapsed: false,
        items: [
          'configuration/project',
          'configuration/content-routing',
          'configuration/i18n',
        ],
      },
    ],
}

Localized Labels

Use translations for labels owned by theme.config.ts. This includes top-level docs nav labels, group labels, and link item labels.

docsNav: [
  {
    slug: 'guide',
    label: 'Guides',
    translations: {
      'zh-cn': '指南',
    },
    items: [
      {
        label: 'Getting Started',
        translations: {
          'zh-cn': '入门',
        },
        items: ['overview', 'installation'],
      },
      {
        label: 'GitHub',
        link: 'https://github.com/prosefly/astro-theme-dahlia',
        external: true,
        translations: {
          'zh-cn': 'GitHub',
        },
      },
    ],
  },
]

String items and autogenerated entries use the localized page’s frontmatter instead. For example, overview displays the Chinese page title when src/content/docs/zh-cn/overview.mdx exists.

Autogenerated Directories

Use autogenerate to include entries from a directory when a section should track the file tree instead of an explicit navigation list.

{ autogenerate: { directory: 'guides' } }

The directory value follows the same locale-neutral rule. For example, guides matches src/content/docs/en/guides for root English pages and src/content/docs/zh-cn/guides for Simplified Chinese pages.

Autogenerated entries are sorted by sidebar.order frontmatter, then by title.

By default, Dahlia renders autogenerated entries as a flat list and includes all descendants under the directory. Add options when a directory needs tighter control.

{
  autogenerate: {
    directory: 'guides',
    structure: 'tree',
    depth: 2,
    exclude: ['drafts/**', '**/internal-*'],
  },
}

Page Ownership

Dahlia determines a page’s active docs section from docsNav. A page belongs to the first top-level docs nav section that lists it directly or includes it through an autogenerated directory.