Group Pages

A group page lists the content of a directory of your docs as link cards and is linked from the sidebar group showing this directory.

Generated pages

The plugin generates a group page for each directory of src/content/docs/ that contains at least one page but has no page of its own. The following content generates group pages at /guides/ and /guides/advanced/:

• Directorysrc/content/docs/

  • index.mdx
  • Directoryguides/

    • installation.mdx
    • deployment.mdx
    • Directoryadvanced/

      • theming.mdx

When a directory has a page, e.g. guides/index.mdx or guides.mdx, no page is generated and the link cards are appended to this page instead. This behavior is controlled by the extendIndexPages option.

The plugin ignores directories matching the exclude option and directories only containing pages hidden from the sidebar.

Generated pages are not entries of the docs content collection. Tools checking links against this collection, e.g. starlight-links-validator, report links to them as invalid unless you exclude these links.

Content

A group page shows one link card for each entry of its sidebar group, in the same order and with the same labels as the sidebar:

• A link to a page displays the page description.
• A nested group links to its own group page and displays the description of its index page or, without one, a summary of its entries, e.g. “Installation, Deployment, and Advanced”.
• A nested group without a group page, e.g. an excluded directory, is rendered as a heading followed by its entries.

The title of a generated page is the label of its sidebar group, and its description is a summary of its entries. Labels are read after all other route middleware ran, so labels changed by your own middleware are used as well. See “Customizing Group Pages” to change the title and the content.

Sidebar and pagination

A sidebar group gets a group page when all the pages it links to, including those of its nested groups, share a directory. This is the case for autogenerated links and for manual groups linking to pages of the same directory:

starlight({
  sidebar: [
    {
      // All pages are in `guides/`: the group page is `/guides/`.
      label: "Guides",
      items: ["guides/installation", "guides/deployment"],
    },
    {
      // Pages from different directories: no group page.
      label: "Start Here",
      items: ["getting-started", "guides/installation"],
    },
  ],
});

By default, the plugin adds an “Overview” link to the group page as the first item of the group, unless the group already links to it. With the sidebarLink option set to label, the group label itself becomes the link instead, and the caret next to it expands and collapses the group.

The link to the group page is part of the previous and next page links, which still respect the prev and next frontmatter fields and the pagination option.

A directory matching no sidebar group still gets a group page. Its link cards list the pages of the directory sorted like autogenerated links: by sidebar.order, then alphabetically.

Multilingual sites

On multilingual sites, group pages exist for every language. Untranslated pages are linked to their fallback content, like in the sidebar. See “Internationalization (i18n)” for more details.