Customizing Group Pages

Group pages are built from your sidebar configuration and the frontmatter of your pages. See “Group Pages” to learn where each part of a group page comes from.

Add an introduction

Create an index page for the directory, e.g. src/content/docs/guides/index.mdx:

src/content/docs/guides/index.mdx

---
title: Guides
description: Step-by-step guides to get the most out of Starlight Rocket.
---

Start with the installation guide if you are new to Starlight Rocket.

The plugin renders your page and appends the link cards of the directory below your content. The page supports all frontmatter fields and components of a regular page. The Reference demo page uses this approach.

Change the title

Generated pages use the label of their sidebar group as title. Change the group label in your sidebar configuration, or add an index page with the title of your choice.

Nested groups of autogenerated links are labeled with their directory name by Starlight, e.g. advanced. To format these labels, update them in a route middleware:

src/routeData.ts

import { defineRouteMiddleware } from "@astrojs/starlight/route-data";

export const onRequest = defineRouteMiddleware((context) => {
  titleCaseGroupLabels(context.locals.starlightRoute.sidebar);
});

function titleCaseGroupLabels(entries) {
  for (const entry of entries) {
    if (entry.type !== "group") continue;

    entry.label = entry.label.charAt(0).toUpperCase() + entry.label.slice(1);
    titleCaseGroupLabels(entry.entries);
  }
}

The plugin reads group labels after your middleware, so group pages, link cards and the sidebar use the same formatted label. See “Autogenerated Starlight sidebar” for more ways to customize autogenerated groups, e.g. ordering directories with numeric prefixes.

Describe the link cards

Add a description to the frontmatter of a page to display it on its link card:

---
title: Installation
description: Install Starlight Rocket in your project.
---

Link cards of nested groups display the description of the group’s index page, or a summary of the group’s entries without one.

To change the label of a link card, change the label of the sidebar entry, e.g. with the sidebar.label frontmatter field.

Change the “Overview” label

Override the starlightGroupPages.sidebarLink UI string in your translation files:

src/content/i18n/en.json

{
  "starlightGroupPages.sidebarLink": "Introduction"
}

See “Internationalization (i18n)” for all UI strings and the languages provided out of the box.

Make group labels clickable

Set the sidebarLink option to label:

starlightGroupPages({
  sidebarLink: "label",
});

The group label links to the group page and the caret next to it expands and collapses the group. This option overrides the Starlight Sidebar component.

Exclude directories

Add the directories to the exclude option:

starlightGroupPages({
  exclude: ["reference/**"],
});