Excluded Pages

By default, the Starlight Sidebar Topics plugin expect that every pages in your project is associated with a topic. This is done by including the page in a topic sidebar configuration or using the topic frontmatter field for unlisted pages.

However, there are cases where you may have custom pages that use a custom site navigation sidebar which do not belong to any topic. Excluding these pages from any topic will prevent the plugin from rendering a list of topics in the sidebar and use the built-in Starlight sidebar instead.

Exclude pages

To exclude some pages from any topic, you can use the exclude plugin configuration option.

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(
          [
            {
              label: 'Guides',
              link: '/guides/',
              items: ['guides/concepts', 'guides/courses'],
            },
          ],
          {
            exclude: ['/changelog', '/changelog/**/*'],
          },
        ),
      ],
      title: 'My Docs',
    }),
  ],
})

For example, given the above configuration and following file structure:

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryguides/

        • concepts.md
        • courses.md
  • Directorypages/

    • changelog.astro
    • …

And the changelog.astro page content rendering the following custom page with a custom site navigation sidebar:

src/pages/changelog.astro

<StarlightPage
  frontmatter={{ title: 'Changelog' }}
  sidebar={[
    { label: 'v3.0.0', link: '/changelog/v3-0-0/' },
    { label: 'v2.0.0', link: '/changelog/v2-0-0/' },
    { label: 'v1.0.0', link: '/changelog/v1-0-0/' },
  ]}
>
  …
</StarlightPage>

Visiting the guides/concepts and guides/courses pages will display the sidebar of the “Guides” topic while the changelog page will use the custom site navigation sidebar defined in the changelog.astro page using the built-in Starlight sidebar.

• guides/concepts and guides/courses are explicitly listed in the “Guides” topic sidebar configuration under the items key.
• changelog is excluded from any topic using the exclude plugin configuration option.