Show documentation type badges

Compass shows a small badge below the title of every page that declares its Diátaxis type, so readers know what to expect before they start reading.

Prerequisites

• A Starlight site with Compass and a provider set up.

Show the badges

1. Extend your docs schema with compassSchema(), so that the diataxis frontmatter field is kept:

   src/content.config.ts

   import { docsSchema } from "@astrojs/starlight/schema";
   import { compassSchema } from "starlight-compass/schema";
   
   docsSchema({ extend: compassSchema() });

2. Declare the type of a page in its frontmatter:

   src/content/docs/guides/deploy.md

   ---
   title: Deploy your site
   diataxis: how-to
   ---

3. Start the dev server. The page shows a badge below its title. Hover over it to read a short description of the type.

Pages without a declared type, or with diataxis: false, show no badge. The diataxis rule can suggest the type of pages without one.

Change the labels

The labels are Starlight UI strings, so you can translate or reword them in a src/content/i18n/en.json file:

src/content/i18n/en.json

{
  "starlightCompass.badge.how-to": "Guide",
  "starlightCompass.badge.how-to.description": "Steps to solve a specific problem."
}

Every type has a label under starlightCompass.badge.<type> and a description under starlightCompass.badge.<type>.description, where <type> is tutorial, how-to, reference or explanation.

Combine with your own PageTitle

Compass adds the badges by overriding Starlight’s PageTitle component. If you already override it, Compass skips the badges and logs a warning. Render the Compass component from your override instead:

src/components/PageTitle.astro

---
import CompassPageTitle from "starlight-compass/components/PageTitle.astro";
---

<CompassPageTitle {...Astro.props}><slot /></CompassPageTitle>

To turn the badges off, set badges to false.