# Sidebars

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

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

```ts
sidebars: [
  {
    slug: 'guide',
    label: 'Guides',
    icon: 'lucide:rocket',
    items: [
      'overview',
      'installation',
      {
        label: 'Configuration',
        items: [{ autogenerate: { directory: 'configuration' } }],
      },
      'deployment',
    ],
  },
  {
    label: 'Components',
    icon: 'lucide:blocks',
    items: [{ autogenerate: { directory: 'components' } }],
  },
]
```

## Sections

Top-level sidebar 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: [{ autogenerate: { directory: 'configuration' } }],
    },
  ],
}
```

## Localized Labels

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

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

```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 `sidebars`. A page belongs to
the first top-level sidebar that lists it directly or includes it through an
autogenerated directory.