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/:

For most tasks, read project-setup.md first, then the topic-specific file.

Core workflow

1. Scaffold the project

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:

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:

---
title: Getting Started
description: How to get started with our product.
sidebar:
  order: 1
---

5. Build and deploy

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/