Skip to content
Devbook

Starlight

Last verified:

View Markdown

Starlight 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

Section titled “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

Section titled “Rules”

Content

Section titled “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.
Section titled “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

Section titled “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)

Section titled “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

Section titled “SEO”
  • Set site so canonicals and the sitemap are generated.
  • Add JSON-LD through a Head override (see structured data).
  • Provide a default Open Graph image via head config.

Checklist

Section titled “Checklist”
  • Every page has title + description
  • Schema extended, not bypassed
  • Sidebar autogenerated with orders
  • Overrides wrap defaults
  • Link validator in the build
Written by Privacy