Getting Started

A Starlight plugin to give your sidebar groups their own pages.

In Starlight, a sidebar group only expands and collapses its items. With this plugin, every group gets a group page listing its content, linked as the first item of the group:

• Directories without an index page get a generated group page.
• Existing index pages keep their content and get the link cards appended.
• The group page is part of the sidebar and the pagination.
• The link cards of a directory can be rendered on any page with the <GroupPageCards> component.

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 Group Pages is a Starlight plugin that you can install using your favorite package manager:

   npm

   npm i starlight-group-pages

   pnpm

   pnpm add starlight-group-pages

   yarn

   yarn add starlight-group-pages

2. Configure the plugin in your Starlight configuration in the astro.config.mjs file.

   astro.config.mjs

   import starlight from '@astrojs/starlight'
   import { defineConfig } from 'astro/config'
   import starlightGroupPages from 'starlight-group-pages'
   
   export default defineConfig({
     integrations: [
       starlight({
         plugins: [starlightGroupPages()],
         title: 'My Docs',
       }),
     ],
   })

3. Start the development server and open the URL of a directory of your docs, e.g. /guides/, to see its group page.

The Starlight Group Pages plugin behavior can be tweaked using various configuration options.

Component overrides

The Starlight Group Pages plugin uses Starlight component overrides for the MarkdownContent component to render the link cards and, when the sidebarLink option is set to label, for the Sidebar component.

If you have a custom MarkdownContent component override in your Starlight project, you will need to manually render the MarkdownContent component from the Starlight Group Pages plugin inside the default component:

src/components/overrides/MarkdownContent.astro

---
import Default from '@astrojs/starlight/components/MarkdownContent.astro'
import StarlightGroupPagesMarkdownContent from 'starlight-group-pages/components/MarkdownContent.astro'
---

<Default>
  <slot />
  <StarlightGroupPagesMarkdownContent />
</Default>
<p>Custom content in the MarkdownContent override</p>

If you have a custom Sidebar component override, render the Sidebar component from starlight-group-pages/components/Sidebar.astro instead of the default Starlight Sidebar component.