Getting Started

This package exposes a dropdown menu component meant to be used as a custom topic list for the Starlight Sidebar Topics plugin.

See it in action

At the top of the sidebar, you can find the dropdown menu in action to switch between the 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.

You will also need to have the Starlight Sidebar Topics plugin installed and configured. If you don’t have it set up yet, you can follow the “Getting Started” guide in the Starlight Sidebar Topics docs.

Installation

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

   npm

   npm i starlight-sidebar-topics-dropdown

   pnpm

   pnpm add starlight-sidebar-topics-dropdown

   yarn

   yarn add starlight-sidebar-topics-dropdown

2. To replace the topic list built into the Starlight Sidebar Topics plugin with the dropdown menu provided by this package, configure a component override in the astro.config.mjs file for the <Sidebar> component:

   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([
             // Your Starlight Sidebar Topics configuration here.
           ]),
         ],
         components: {
           // Override the default `Sidebar` component with a custom one.
           Sidebar: './src/components/Sidebar.astro',
         },
         title: 'My Docs',
       }),
     ],
   })

3. Create an Astro component to replace the default Starlight <Sidebar> component, which will render the topic list dropdown menu and reuse the default Starlight sidebar:

   src/components/Sidebar.astro

   ---
   import Default from '@astrojs/starlight/components/Sidebar.astro';
   import TopicsDropdown from 'starlight-sidebar-topics-dropdown/TopicsDropdown.astro';
   ---
   
   {/* Render the topics dropdown menu. */}
   <TopicsDropdown />
   {/* Render the default sidebar. */}
   <Default><slot /></Default>

4. Start the development server to preview the changes.

You can also render the dropdown menu in a different location in your website by overriding different components. Learn more about overriding components in the Starlight docs.

The dropdown menu is only rendered on pages with a sidebar that are associated with a topic, e.g. it is not displayed on excluded pages.