Getting Started

An opinionated Starlight plugin to split your documentation into different sections, called topics, each with its own sidebar.

Topics 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. Topics are listed above the default Starlight sidebar links and can be used to navigate between different sections of your documentation.

See it in action

At the top of the sidebar, you can find links to different topics used in this documentation, such as “Documentation” and “Demo” that each have their own sidebar configuration, while the “Starlight Docs” topic is a direct link to the Starlight documentation.

Prerequisites

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Installation

1. Starlight Sidebar Topics is a Starlight plugin. Install it using your favorite package manager:

   npm

   npm i starlight-sidebar-topics

   pnpm

   pnpm add starlight-sidebar-topics

   yarn

   yarn add starlight-sidebar-topics

   ni

   ni starlight-sidebar-topics

2. Configure the plugin in your Starlight configuration in the astro.config.mjs file by specifying an array of topics each with its own sidebar configuration.

   The following example shows how to configure two new topics named “Guides” and “Reference” linking to the /guides/ and /reference/ pages respectively with their own sidebar 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',
               link: '/guides/',
               icon: 'open-book',
               items: ['guides/getting-started', 'guides/manual-setup'],
             },
             {
               label: 'Reference',
               link: '/reference/',
               icon: 'information',
               items: ['reference/api', 'reference/components'],
             },
           ]),
         ],
         sidebar: [
           {
             label: 'Guides',
             items: ['guides/getting-started', 'guides/manual-setup'],
           },
           {
             label: 'Reference',
             items: ['reference/api', 'reference/components'],
           },
         ],
         title: 'My Docs',
       }),
     ],
   })

3. Start the development server to preview the changes.

The Starlight Sidebar Topics plugin behavior can be tweaked using various topic configuration options.