Skip to main content

Astro Starlight

What is Astro Starlight​

Astro Starlight is a full-featured documentation framework built on top of the Astro web framework, published as @astrojs/starlight. It is MIT licensed and currently at version 1.x. With ~300k weekly npm downloads and ~6k GitHub stars, it is the standard way to build documentation sites within the Astro ecosystem.

Why we recommend it​

  • Zero JS by default — inherits Astro's zero-JS-by-default model. Documentation pages ship as pure HTML unless a component explicitly opts in via island hydration. Excellent Lighthouse scores out of the box.
  • Built-in offline search (Pagefind) — zero-config full-text search powered by Pagefind, compiled at build time. No external service, no API keys.
  • Expressive Code syntax highlighting — advanced code blocks with file titles, diff highlighting, line markers, and terminal frame styles.
  • First-party MDX components — <Aside>, <Card>, <CardGrid>, <Tabs>, <Steps>, and <LinkCard> are available out of the box. No need to build or source common documentation UI patterns.
  • Auto-generated sidebar — driven by the file system and frontmatter; no manual sidebar.js maintenance.
  • i18n with RTL support — built-in internationalisation consistent with Astro's own i18n routing, including right-to-left language support.
  • Multi-framework islands — React, Vue, Svelte, and Solid components can be embedded as Astro islands inside documentation pages.
  • Dark/light mode — included in the default theme, no configuration needed.

When to use​

  • Documentation sites built on Astro, or where the team wants to stay in the Astro ecosystem
  • Projects prioritising minimal bundle size and maximum page performance
  • Standalone product or library docs where offline search without an external service is a requirement
  • Docs sites that do not need built-in versioning
tip

Pagefind search works entirely at build time — no external service, no cost, and no data leaving your infrastructure. This makes Starlight a strong choice for internal or confidential documentation sites.

When NOT to use​

  • Projects that need multiple versioned documentation releases maintained in parallel — Starlight has no built-in versioning; use Docusaurus instead
  • Projects not already using Astro where introducing a new framework solely for docs is not justified
  • Documentation sites that need a first-class integrated blog
tip

Starlight follows semantic versioning from v1.0 onward. Check the changelog before major version upgrades.

Resources​