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

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

• Design folder structure before writing content. Restructuring later means broken links and sidebar chaos.
• Keep sidebar config explicit rather than fully auto-generated — you'll want control over ordering and grouping.
• Use .mdx only when you need component imports. Plain .md is simpler and avoids hydration issues.
• Test deployment early, especially if hosting at a subpath. Don't wait until the end.
• Keep CSS overrides minimal. Work with Starlight's design tokens (CSS custom properties) rather than fighting its defaults.
• 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/