astro-starlight

# Astro Starlight Skill Build production-grade documentation sites with Astro Starlight. This skill covers everything from initial scaffolding to advanced customization and deployment. ## When to use this skill - Creating a new documentation site from scratch - Adding Starlight to an existing Astro project - Configuring sidebar navigation (manual, autogenerated, or mixed) - Styling/theming a Starlight site (custom CSS, Tailwind, dark mode) - Using MDX components inside docs (Tabs, Cards, Asides, Code, etc.) - Deploying to subpaths (`/docs/`), Vercel, Netlify, Cloudflare Pages - Setting up search (Pagefind, Algolia) - Internationalization (i18n) - Overriding built-in components - Troubleshooting common issues (404s, broken links, sidebar mismatches) ## Quick orientation Before writing any code, read the relevant reference file(s) from `references/`: | Task | Read first | |---|---| | New project or project structure | `references/project-setup.md` | | Sidebar, navigation, frontmatter | `references/sidebar-and-content.md` | | Styling, theming, Tailwind | `references/styling-and-theming.md` | | MDX components, custom components | `references/components.md` | | Deployment, subpaths, search, i18n | `references/deployment-and-advanced.md` | | Something broken? | `references/troubleshooting.md` | For most tasks, read `project-setup.md` first, then the topic-specific file. ## Core workflow ### 1. Scaffold the project ```bash npm create astro@latest -- --template starlight ``` This gives you a working project with: ``` my-docs/ ├── astro.config.mjs # Starlight integration config ├── src/ │ ├── content/ │ │ └── docs/ # All doc pages live here │ │ └── index.mdx │ └── content.config.ts # Content collection schema ├── public/ # Static assets (favicon, images) └── package.json ``` ### 2. Design folder structure FIRST This is the most important step. Your folder structure = your URL structure = your sidebar structure. Plan it before writing content. See `references/sidebar-and-content.md` for patterns. ### 3. Configure `astro.config.mjs` The Starlight integration is configured here. Minimum viable config: ```js import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; export default defineConfig({ integrations: [ starlight({ title: 'My Docs', sidebar: [ { label: 'Guides', autogenerate: { directory: 'guides' }, }, ], }), ], }); ``` ### 4. Write content in `src/content/docs/` Every `.md` or `.mdx` file needs frontmatter with at least `title`: ```yaml --- title: Getting Started description: How to get started with our product. sidebar: order: 1 --- ``` ### 5. Build and deploy ```bash npm run build # Outputs to dist/ npm run preview # Preview the build locally ``` ## Key principles 1. **Design folder structure before writing content.** Restructuring later means broken links and sidebar chaos. 2. **Keep sidebar config explicit** rather than fully auto-generated — you'll want control over ordering and grouping. 3. **Use `.mdx` only when you need component imports.** Plain `.md` is simpler and avoids hydration issues. 4. **Test deployment early**, especially if hosting at a subpath. Don't wait until the end. 5. **Keep CSS overrides minimal.** Work with Starlight's design tokens (CSS custom properties) rather than fighting its defaults. 6. **Use frontmatter `sidebar.order`** to control page ordering within autogenerated groups. ## Important gotchas (read these) - **Subpath deployment is the #1 source of bugs.** If deploying to `/docs/`, you must set both `site` and `base` in `astro.config.mjs`. See `references/deployment-and-advanced.md`. - **MDX imports only work in `.mdx` files**, not `.md`. If you get import errors, check your file extension. - **Sidebar config and filesystem must agree.** A page that exists on disk but isn't in the sidebar config (or vice versa) causes confusing 404s or missing nav items. - **Tailwind + Starlight requires the `@astrojs/starlight-tailwind` compatibility package.** Without it, styles will fight each other. - **Pagefind search breaks on subpaths** if `base` isn't configured correctly. - **Custom components need `client:load`** (or another client directive) if they use JavaScript/interactivity. Without it, they render as static HTML only. ## Reference files Read these for detailed guidance. Each is self-contained and covers one topic area thoroughly: - `references/project-setup.md` — Scaffolding, project structure, `astro.config.mjs` anatomy, content collections - `references/sidebar-and-content.md` — Sidebar config patterns, frontmatter reference, content authoring, ordering - `references/styling-and-theming.md` — Custom CSS, Tailwind integration, theming, dark mode, Expressive Code - `references/components.md` — Built-in components (Tabs, Cards, Asides, etc.), custom components in MDX, hydration - `references/deployment-and-advanced.md` — Deployment targets, subpath hosting, search, i18n, versioning, auth, SSR - `references/troubleshooting.md` — Diagnosis and fixes for the most common Starlight issues ## Useful links - Docs: https://starlight.astro.build - GitHub: https://github.com/withastro/starlight - Config reference: https://starlight.astro.build/reference/configuration/ - Frontmatter reference: https://starlight.astro.build/reference/frontmatter/ - Component list: https://starlight.astro.build/components/using-components/ - Community plugins: https://starlight.astro.build/resources/plugins/