Starlight

One Markdown file per page, inside an Astro project

Starlight is a full documentation theme for Astro, installed as an Astro integration. Every Markdown or MDX file under src/content/docs/ becomes a page, and Starlight supplies the sidebar navigation, search, dark mode and code highlighting around it. A new project starts from the official template (npm create astro@latest -- --template starlight); an existing Astro site adds it with npx astro add starlight. By default, docs pages are prerendered to HTML at build time, even when the rest of the project renders on the server.

Pagefind search, typed frontmatter, UI strings in 36 languages

• Search without an external service: a Pagefind index is generated with the site and opens on Ctrl+K or Cmd+K. A page opts out with pagefind: false, and the official @astrojs/starlight-docsearch plugin swaps Pagefind for Algolia DocSearch when a project has been accepted into that program.
• Frontmatter checked against a typed schema: docsSchema() defines the fields each page accepts, and its extend option adds project-specific ones.
• Translations with a fallback: one folder per language, pages paired by file name. An untranslated page shows the default-language content along with a notice saying so. Right-to-left scripts are supported, and the interface labels ship in 36 languages.
• React, Vue, Svelte or Solid components in MDX: Astro islands keep them from sending JavaScript to the browser until hydration is explicitly requested.
• Several layers of customization: CSS custom properties, styles kept in an @layer starlight cascade layer, Tailwind CSS v4 support, and component overrides that swap parts of the UI (header, search, language picker, footer) for Astro components.

Still beta at 0.42, Astro 7.2.10 required, no search in dev

The project still describes itself as beta software. The getting-started guide uses those words and warns of frequent updates. The 0.42 line went through eight releases between September 2 and October 23, 2026, when 0.42.7 shipped, and the latest commit is from October 27, 2026.

A minor version can force a migration. 0.41.0, released June 23, 2026, dropped Astro 6 for Astro 7. 0.42.0 requires Astro 7.2.10 or later and ends official support for Chromium-based browsers before version 116, Safari before 17.0 and Firefox before 125. Starlight and Astro are meant to be upgraded together (npx @astrojs/upgrade), and the changelog warns that community plugins may need manual updates.

Starlight only runs inside an Astro project. Configuration lives in astro.config.mjs, content in Astro content collections, and the getting-started guide sends readers to the Astro docs for anything Starlight's own docs leave out. Serving the docs under a subpath means nesting a folder inside src/content/docs/, a workaround the project says it plans to remove.

Search does not work on the dev server. The Pagefind index only exists after a build. In dev mode, the search dialog says it is only available in production builds and suggests building and previewing the site instead.

The project publishes its own page-weight figures. Its "Eco-friendly docs" page puts a first visit at under 50 KB of compressed data. The same page lists Website Carbon Calculator results collected on April 21, 2026: 0.01 g of CO₂ per visit for a Starlight docs page, against 0.04 g for VitePress and 0.09 g for Docusaurus, each tool measured on its own documentation.