Home › Astro › Astro Starlight docs Windsurf rules

Astro Starlight docs Windsurf rules

Windsurf rules for documentation sites built with Astro Starlight: content structure, frontmatter, components, and links.

WindsurfAstro

Copy starlight.md

How to use

Save this as .windsurf/rules/starlight.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

---
trigger: glob
globs: src/content/docs/**,astro.config.mjs
---

# Astro Starlight docs

- Pages live in `src/content/docs/` as `.md`/`.mdx`. The file path is the URL; use lowercase kebab-case names.
- Every page has frontmatter with `title` and `description`; set `sidebar: { order, label, badge }` when ordering matters.
- Sidebar structure is configured in `astro.config.mjs` (`starlight({ sidebar: [...] })`), using `autogenerate: { directory: 'guides' }` for folders. Update it when adding sections.
- Use built-in components in `.mdx` from `@astrojs/starlight/components`: `<Aside type="tip|note|caution|danger">`, `<Tabs>`/`<TabItem>`, `<Steps>`, `<Card>`/`<CardGrid>`, `<LinkCard>`, `<FileTree>`, `<Code>`. Don't hand-build callouts with raw HTML.
- Code blocks have a language and, when useful, a title (```` ```ts title="src/env.ts" ````). Use Expressive Code features (line highlights, `ins`/`del`) instead of comments like "// changed".
- Internal links are root-relative without the file extension (`/guides/install/`); check that they resolve.
- Images go in `src/assets/` and are referenced relatively so Astro optimizes them; always include alt text.
- Structure: Getting started -> Guides (tasks) -> Reference (APIs/config) -> Concepts. One topic per page.
- For i18n sites, add translations under the locale folder with the same file path.

## Done
`npm run build` succeeds (it fails on broken internal links if link validation is configured) and the page appears in the sidebar where expected.