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.
          ],
          {
            // Plugin configuration goes here (optional).
          },
        ),
      ],
      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',
  },
])

link

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' },
  },
])

Plugin configuration

The Starlight Sidebar Topics plugin accepts an optional configuration object as the second argument.

The configuration object can be used to customize the plugin global behavior and the following options are available:

exclude

type: string[]
default: []

A list of pages or glob patterns that should be excluded from any topic.

This option can be useful for custom pages that use a custom site navigation sidebar which do not belong to any topic. Excluded pages will use the built-in Starlight sidebar and not render a list of topics.

The following example excludes all pages under the /blog/ directory from any topic:

starlightSidebarTopics(
  [
    {
      label: 'Guides',
      link: '/guides/',
      items: ['guides/concepts', 'guides/courses'],
    },
  ],
  {
    exclude: ['/blog', '/blog/**/*'],
  },
)

See the “Excluded Pages” guide to learn how to exclude content pages from any topic.

Dica

You can use this webpage to generate and test glob patterns.

topics

type: Record<string, string[]>
default: {}

A map of topic identifiers to a list of pages or glob patterns that should be associated with the topic.

This option can be useful for custom pages generated and included in the sidebar by other plugins that have no knowledge of the Starlight Sidebar Topics plugin that should be associated with a specific topic.

The following example associates all pages under the /reference/api/ directory with the reference topic:

starlightSidebarTopics(
  [
    {
      label: 'Reference',
      id: 'reference',
      link: '/reference/',
      items: ['reference/configuration'],
    },
  ],
  {
    topics: {
      reference: ['/reference/api', '/reference/api/**/*'],
    },
  },
)

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

Dica

You can use this webpage to generate and test glob patterns.