Starlight

Starlight is a full-featured documentation-site framework built on top of Astro. Rather than being a general-purpose UI library, it is an Astro integration that takes over the routing, content-collection schema, layout, and navigation for an entire docs site, so teams get a working, accessible, fast documentation site out of the box and only customize what they need. It ships sensible defaults for sidebar navigation, full-text search, internationalization, dark/light theming, and Markdown/MDX/Markdoc content authoring, while remaining fully overridable via component overrides, a plugin system, and custom Astro components dropped into the page.

What You Get

• A pre-built, accessible documentation layout (header, sidebar, table of contents, pagination, edit-this-page links) with zero custom component code required to start
• Built-in full-text search powered by Pagefind, generated automatically at build time with no external service to configure
• First-class internationalization: per-locale content collections, automatic language selector, and RTL support
• A content-collection frontmatter schema (Zod-based) for docs pages covering titles, descriptions, hero sections, table-of-contents overrides, and custom head tags
• A component-override system so any built-in UI piece (sidebar, header, TOC, footer) can be swapped for a custom Astro component without forking the framework
• A plugin API that lets third-party packages inject routes, translations, and Astro integrations into a Starlight site (used by starlight-markdoc, starlight-tailwind, and community plugins)
• Syntax highlighting and code annotations via Expressive Code, bundled and pre-configured

Common Use Cases

• Product and API documentation sites for open-source projects or SaaS products
• Internal engineering knowledge bases and runbooks that need search and versioned navigation
• Multi-language documentation portals where content is maintained per-locale
• Migrating an existing docs site off Docusaurus, VitePress, or GitBook onto the Astro ecosystem for better performance

Under The Hood

Architecture — Starlight is registered as a single Astro integration (index.ts) whose astro:config:setup hook does the real work: it runs any configured plugins (utils/plugins.ts) to merge in extra config, translations, and Astro integrations, validates the final config against a Zod schema (utils/user-config.ts), injects its own routes under routes/static and routes/ssr depending on the build output mode, adds rehype/remark markdown plugins for directives and Expressive Code, and registers a Vite plugin (integrations/vite-virtual-modules.ts) that exposes the resolved config to components as a virtual module. Content flows from an Astro content collection (docs), validated through schema.ts, into .astro page components in user-components/ and components/ that render the shared Page.astro shell (header, sidebar, TOC, pagination). Tech Stack — Written almost entirely in TypeScript and .astro files, it depends on astro (^7.0.2) and @astrojs/markdown-remark as peers, and pulls in @astrojs/mdx, @astrojs/sitemap, astro-expressive-code for syntax highlighting, pagefind/@pagefind/default-ui for search, i18next for translation lookup, and the unified/remark/rehype ecosystem for markdown/HTML transforms; the monorepo is managed with pnpm workspaces and Changesets, with sibling packages for Markdoc, Tailwind, and DocSearch integrations. Code Quality — The packages/starlight/__tests__ and __e2e__ directories contain over 100 test fixture projects covering i18n edge cases, sidebar generation, plugin behavior, and build-format variations, run via Vitest and Playwright; the codebase uses strict TypeScript throughout, Zod schemas for all user-facing config surfaces (giving friendly runtime validation errors via utils/error-map.ts), and consistent naming between the public API (schema.ts, props.ts, types.ts) and internal implementation. API Design — Getting started requires adding one integration call with a title and social/sidebar config to astro.config.mjs; the public export map (./components, ./schema, ./loaders, ./props) is deliberately narrow and documented, and component overrides use a single components config key rather than requiring users to eject the whole layout, keeping the common path low-boilerplate while still exposing deep customization for advanced users.