Skip to content
Starlight Sidebar Topics

Configuration

The Starlight Sidebar Topics can be configured inside the astro.config.mjs configuration file of your project:

astro.config.mjs
// @ts-check
import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightSidebarTopics from 'starlight-sidebar-topics'


export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightSidebarTopics([
          // Topics configuration goes here.
        ]),
      ],
      title: 'My Docs',
    }),
  ],
})

Topic configuration

The Starlight Sidebar Topics plugin accepts an array of topics to display in the sidebar.

A topic can represent either a section of your documentation with its own sidebar configuration or a direct link to a specific URL, such as an external resource.

starlightSidebarTopics([
  // A topic representing a guide section of your project.
  {
    label: 'Guides',
    icon: 'open-book',
    // The page to link to when the topic is clicked.
    link: '/guides/',
    // The sidebar configuration for the topic.
    items: [
      {
        label: 'Start Here',
        items: ['guides/concepts', 'guides/courses'],
      },
      { label: 'Recipes', autogenerate: { directory: 'guides/recipes' } },
    ],
  },
  // A topic redirecting to the Starlight documentation.
  {
    label: 'Starlight docs',
    icon: 'starlight',
    // The URL to the external resource to link to.
    link: 'https://starlight.astro.build',
  },
])

A topic can be configured using the following options:

label

required
type: string | Record<string, string>

The topic label visible at the top of the sidebar.

The value can be a string, or for multilingual sites, an object with values for each different locale. When using the object form, the keys must be BCP-47 tags (e.g. en, fr, or zh-CN):

starlightSidebarTopics([
  {
    label: {
      en: 'Starlight documentation',
      fr: 'Documentation de Starlight',
    },
    link: 'https://starlight.astro.build',
  },
])

required
type: string

The link to the topic’s content which an be a relative link to local files or the full URL of an external page.

For internal links, the link can either be a page included in the items array or a different page acting as the topic’s landing page.

starlightSidebarTopics([
  {
    label: 'Starlight docs',
    link: 'https://starlight.astro.build',
  },
])

items

type: SidebarItem[]

The topic’s sidebar navigation items. This represents the sidebar displayed when the topic link page or any of the pages configured in the items array is the current page.

This option accepts the same configuration as the Starlight sidebar configuration.

starlightSidebarTopics([
  {
    label: 'Guides',
    link: '/guides/',
    items: [
      {
        label: 'Start Here',
        items: ['guides/concepts', 'guides/courses'],
      },
      { label: 'Recipes', autogenerate: { directory: 'guides/recipes' } },
    ],
  },
])

See the “Sidebar Navigation” guide in the Starlight docs to learn more about sidebar configuration.

id

type: string

An optional unique identifier for the topic that can be used to associate content pages that are not listed in any topic sidebar configuration with this topic.

starlightSidebarTopics([
  {
    label: 'Guides',
    link: '/guides/',
    id: 'guides',
    items: [{ label: 'Start Here', autogenerate: { directory: 'guides' } }],
  },
])

See the “Unlisted Pages” guide to learn how to associate content pages with a specific topic.

icon

type: string

The name of an optional icon to display before the topic label set to one of Starlight’s built-in icons.

starlightSidebarTopics([
  {
    label: 'Starlight docs',
    link: 'https://starlight.astro.build',
    icon: 'starlight',
  },
])

badge

type: string | BadgeConfig

An optional badge to display next to the topic label.

This option accepts the same configuration as the Starlight badge sidebar item configuration.

starlightSidebarTopics([
  {
    label: 'Starlight docs',
    link: 'https://starlight.astro.build',
    badge: { text: 'Official', variant: 'success' },
  },
])