| name | stack-starlight |
| description | Astro Starlight documentation framework — setup, sidebar navigation, frontmatter, built-in components, asides, theming, i18n, search |
| license | Apache-2.0 |
| metadata | {"author":"manuel-retamozo-garcia","version":"1.0"} |
| capabilities | ["starlight"] |
Starlight Patterns
Documentation-site patterns for Starlight (Astro) projects. Covers project setup, astro.config.mjs configuration, sidebar navigation, page frontmatter, built-in components, Markdown authoring extensions, theming, and i18n.
When to Use
- Scaffolding a docs site (
npm create astro@latest -- --template starlight)
- Configuring the
starlight() integration in astro.config.mjs
- Building or reorganizing sidebar navigation
- Authoring pages in
src/content/docs/ (frontmatter, asides, code blocks)
- Using built-in components (Tabs, Cards, Steps, FileTree, etc.)
- Creating custom pages/layouts with
<StarlightPage> or overriding UI components
- Customizing theme (logo, fonts,
--sl-* CSS custom properties) or setting up i18n
Core Rules
- File-Based Content: Pages live in
src/content/docs/; folders become URL segments. Every page MUST have title in frontmatter — the schema validates and fails the build without it.
- Config Entry Point: All site behavior is configured in the
starlight({ ... }) integration inside astro.config.mjs. title is required; set Astro's site to enable sitemap generation.
- Sidebar Strategy: Prefer
autogenerate: { directory } per section over hand-listing slugs; control order/label/visibility per page with the sidebar frontmatter field (order, label, hidden, badge).
- Components Need MDX: Built-in components import from
@astrojs/starlight/components and only work in .mdx (or Markdoc {% %} tags). Plain .md supports asides (:::note … :::) and Expressive Code markers — do not put JSX in .md.
- Custom Pages, Not Forks: For non-docs pages use
src/pages/*.astro wrapped in <StarlightPage frontmatter={{ title }}>; to change built-in UI use the components config override map — never copy/patch theme internals.
- Theming via Custom Properties: Customize with
customCss files overriding --sl-* custom properties (colors, --sl-font); use logo.light/logo.dark for theme-aware logos. Apply not-content class to opt elements out of content styling.
- Search & Visibility: Pagefind search is on by default; exclude a page with
pagefind: false and keep it out of production builds with draft: true.
- i18n Layout: Declare
locales/defaultLocale in config; mirror content per locale directory. Untranslated pages fall back to the default locale automatically; translate sidebar labels with translations.
References
For full configuration options, frontmatter fields, component catalog, and code examples, refer to:
