Choosing Astro or Starlight for docs is mostly about how standard your docs need to be. Starlight, Astro’s official documentation framework, gives you navigation, search, internationalisation, dark mode, table of contents and accessible components with almost no setup. Choose plain Astro when the docs are a small part of a branded marketing site and must share its exact design, or when your docs need a structure Starlight doesn’t fit.
Key Takeaways
- Starlight: the fastest route to complete, accessible docs.
- Plain Astro: full design control, but you build navigation, search and i18n yourself.
- You can run Starlight alongside other Astro pages in the same project.
- Both use content collections, so Markdown content moves between them easily.
Decision flow
- Is this a standalone docs site (
docs.example.com)? Yes → Starlight. - Do you need built-in search, versioned sidebars, or translations? Yes → Starlight.
- Must the docs look identical to a custom marketing site? Yes → plain Astro, or Starlight with heavy custom CSS and component overrides.
- Are the docs a handful of pages? Yes → plain Astro is often simpler.
- Otherwise → Starlight.
Compared
| Starlight | Plain Astro | |
|---|---|---|
| Setup | npm create astro@latest -- --template starlight |
Build layouts yourself |
| Sidebar | Config or autogenerated from folders | Hand-built |
| Search | Built in (Pagefind) | Add Pagefind or a search service |
| i18n | Built in | Astro i18n routing + your UI |
| Table of contents | Built in | From render() headings |
| Components | Tabs, cards, asides, steps, code features | Your own |
| Theming | CSS custom properties, component overrides | Anything |
| Frontmatter | Starlight schema (extendable) | Your schema |
Running both in one project
Starlight is an integration. It serves your docs collection while ordinary Astro pages in src/pages/ keep working, so a marketing home page and a Starlight docs section can live in one repository and deploy together.
// astro.config.mjs
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: 'Acme Docs',
sidebar: [{ label: 'Guides', autogenerate: { directory: 'guides' } }],
}),
],
});Customising Starlight
- Colours and fonts through CSS custom properties.
- Replace built-in components (header, footer, sidebar) with your own via component overrides.
- Add your own frontmatter fields by extending
docsSchema().
The field list is in the Starlight frontmatter cheatsheet.
Docs as part of a themed site
If your docs sit inside a branded site, a documentation theme can give you the layout and navigation already matched to its design. Compare documentation themes with Starlight’s defaults before deciding, and see the Astro content collections guide for how docs content is structured either way. Starlight’s getting started guide covers setup.
FAQ
Is Starlight free?
Yes. It’s open source and maintained by the Astro team.
Can I migrate from Starlight to plain Astro later?
Yes. The Markdown content carries over; you’d rebuild layouts, sidebar and search yourself.