Páginas não listadas

By default, the Starlight Sidebar Topics plugin expect that every content pages in your project is associated with a topic. This is done by including the content page in a topic sidebar configuration and the plugin will automatically determine which sidebar to display based on the current page.

However, there are cases where you may want to have a content page that is not listed in any topic sidebar while still displaying the sidebar of a specific topic or to associate custom pages generated and included in the sidebar by other plugins with a specific topic.

Create a topic ID

To associate unlisted pages with a specific topic, the topic must define an id in its configuration:

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',
            icon: 'open-book',
            link: '/guides/',
            // ID used to associate content pages with this topic.
            id: 'guides',
            items: ['guides/concepts', 'guides/courses'],
          },
        ]),
      ],
      title: 'My Docs',
    }),
  ],
})

Two approaches can be used to associate unlisted pages with a specific topic by either using the topic frontmatter field or the topics configuration option.

Use the topic frontmatter field

Unlisted pages can be associated with a specific topic by using the topic frontmatter field in the page’s content file. This approach allows you to colocate the topic association with the content page itself.

Configure content collections

Starlight is built on top of Astro’s content collections, which are configured in the src/content.config.ts file.

To add support for unlisted content pages, update the content config file to add support for associating content pages with a specific topic:

src/content.config.ts

import { defineCollection } from 'astro:content'
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema'
import { topicSchema } from 'starlight-sidebar-topics/schema'

export const collections = {
  docs: defineCollection({
    loader: docsLoader(),
    schema: docsSchema({ extend: topicSchema })
  }),
}

Associate a page with a topic

To associate an unlisted content page with a specific topic, you can use the topic frontmatter field in the page’s content file:

src/content/docs/guides/support.md

---
title: Support
topic: guides
---

This is the support page.

For example, given the following file structure based on this guide:

• Diretóriosrc/

  • Diretóriocontent/

    • Diretóriodocs/

      • Diretórioguides/

        • concepts.md
        • courses.md
        • support.md

Visiting the guides/concepts, guides/courses, and guides/support pages will all display the sidebar of the “Guides” topic.

• guides/concepts and guides/courses are explicitly listed in the “Guides” topic sidebar configuration under the items key.
• guides/support is not listed in the “Guides” topic sidebar configuration but is associated with the “Guides” topic through the topic: guides frontmatter entry.

Use the topics configuration option

Unlisted custom pages generated and included in the sidebar by other plugins can be associated with a specific topic by using the topics plugin configuration option. This approach allows you to associate custom pages with a specific topic without modifying the content page itself which can be useful for pages generated by other plugins that have no knowledge of the Starlight Sidebar Topics plugin.

Associate pages with a topic

To associate unlisted custom pages with a specific topic, you can use the topics configuration option in the plugin configuration:

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',
              icon: 'open-book',
              link: '/guides/',
              // ID used to associate content pages with this topic.
              id: 'guides',
              items: ['guides/concepts', 'guides/courses'],
            },
          ],
          {
            topics: {
              // Associate custom pages with the "Guides" topic.
              guides: ['/guides/api', '/guides/api/**/*'],
            },
          },
        ),
      ],
      title: 'My Docs',
    }),
  ],
})

For example, given the following file structure based on this guide where all files under the api/ directory are generated and included in the sidebar by another plugin:

• Diretóriosrc/

  • Diretóriocontent/

    • Diretóriodocs/

      • Diretórioguides/

        • concepts.md
        • courses.md
        • Diretórioapi/

          • reference.md

Visiting the guides/concepts, guides/courses, and guides/api/reference pages will all display the sidebar of the “Guides” topic.

• guides/concepts and guides/courses are explicitly listed in the “Guides” topic sidebar configuration under the items key.
• guides/api/reference is not listed in the “Guides” topic sidebar configuration but is associated with the “Guides” topic through the topics plugin configuration option.