# Docs Navigation

Configure docs sections, subnav items, sidebar groups, and generated entries.

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

```json title="theme.config.json"
{
  "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 `lotus({...})` in `astro.config.ts`:

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

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

`slug` is optional. If omitted, Lotus 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`.

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

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

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

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

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

String badges render as trailing neutral badges.

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

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

```ts
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-lotus',
        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.

```ts
{ autogenerate: { directory: 'components' } }
```

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

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

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

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

| Option | Default | Description |
| --- | --- | --- |
| `directory` | required | Locale-neutral docs directory to read from. |
| `structure` | `'flat'` | Use `'tree'` to preserve nested folders as collapsible sidebar groups. |
| `depth` | all descendants | Maximum depth to include relative to `directory`. For `directory: ''`, the default is direct children only. |
| `exclude` | none | Glob pattern or array of patterns matched against both the full slug and the slug relative to `directory`. Supports `*` and `**`. |

## Page Ownership

Lotus 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.