# Starlight

> Starlight stack profile for documentation sites - setup, frontmatter schema extension, sidebar, component overrides, plugins, search and theming rules.

[Starlight](https://starlight.astro.build/) is Astro's documentation theme. It provides navigation, search (Pagefind), dark mode, i18n and accessible defaults. Use it for any docs or guide site.

## Setup
- New project: `npm create astro@latest -- --template starlight`.
- Existing project with content: follow the **manual setup** in the Starlight docs.
- Update with `npx @astrojs/upgrade` (updates Astro and official integrations together).

## Rules

### Content
- Pages live in `src/content/docs/`; the file path is the URL.
- Every page has `title` and `description` (the description is the meta description; keep it 120–160 characters).
- Extend the schema rather than inventing ad-hoc fields: `docsSchema({ extend: z.object({ lastVerified: z.coerce.date().optional() }) })`. Confirm the current API in the docs.
- Use Starlight's components (`Aside`, `Tabs`, `Steps`, `Card`, `LinkCard`, `Code`) instead of custom HTML.
- To show a file's contents on a page, import it with `?raw` and render with `<Code>`, so there is one source of truth.

### Navigation
- Configure each sidebar group as `{ label: 'Group', items: [{ autogenerate: { directory: 'folder' } }] }` and control order with `sidebar.order` in frontmatter. (Putting `label` directly on an `autogenerate` object was removed in Starlight 0.39.)
- Keep groups shallow (two levels).

### Customising
- Theme through CSS custom properties in a `customCss` file (accent and gray scales, fonts).
- Change behaviour through **component overrides** in `components`, importing and wrapping the default component rather than copying it.
- Turn on `lastUpdated` (needs full git history in CI) and `editLink`.

### Plugins (verify before adding)
- `starlight-links-validator`: fail the build on broken internal links.
- `starlight-llms-txt`: generate `llms.txt` files for language models.
- Add any other plugin only with an ADR; community plugins vary in maintenance.

### SEO
- Set `site` so canonicals and the sitemap are generated.
- Add JSON-LD through a `Head` override (see [structured data](/web/structured-data/)).
- Provide a default Open Graph image via `head` config.

## Checklist
- [ ] Every page has title + description
- [ ] Schema extended, not bypassed
- [ ] Sidebar autogenerated with orders
- [ ] Overrides wrap defaults
- [ ] Link validator in the build