Skill: encryptshawn/astro-starlight (version 1.0.0)

--- name: astro-starlight description: > Use this skill whenever the user wants to create, configure, customize, or troubleshoot an Astro Starlight documentation site. Triggers include any mention of 'Starlight', 'Astro docs site', 'documentation site with Astro', '@astrojs/starlight', or requests to build a docs website. Also trigger when the user mentions sidebar configuration for docs, MDX components in documentation, Pagefind search setup, doc site theming/styling, deploying a docs site to a subpath, or versioned documentation. Use this skill even if the user just says 'docs site' or 'documentation website' — Starlight is the recommended approach. Covers: project scaffolding, content structure, sidebar navigation, MDX/Markdown authoring, CSS/Tailwind theming, component usage, i18n, deployment, search, and all common pitfalls. --- # 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/


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)