~2-3 hoursbeginner6 steps

Good documentation is the difference between a tool people adopt and one they abandon. Astro Starlight is purpose-built for documentation sites — it gives you sidebar navigation, full-text search, syntax highlighting, and i18n support out of the box with zero JavaScript shipped to the client by default. This guide walks you through building a complete documentation site from scratch, with custom components and automated deployment.

Prerequisites

→
Node.js 20+
Astro requires Node.js 20 or later. Starlight uses Astro's latest features.
→
Markdown / MDX Knowledge
Documentation pages are written in Markdown or MDX. Familiarity with frontmatter, headings, and code fences is essential.
→
A Project to Document
Have a library, API, or tool ready to write docs for. Even a personal project works as a starting point.

Create the Starlight Project

Scaffold a new Astro project using the Starlight template. Starlight pre-configures everything a docs site needs: sidebar, search, dark mode, responsive layout, and accessibility. The template includes example pages you can replace with your own content.

bash

npm create astro@latest -- --template starlight my-docs
cd my-docs
npm install

Tip: Starlight ships zero client-side JavaScript by default — your docs load almost instantly on any connection.

Tip: Run 'npm run dev' immediately after setup to see the default site at localhost:4321.

Configure Sidebar Navigation and Site Metadata

Edit the Astro config file to define your sidebar structure, site title, and social links. Starlight's sidebar supports nested groups, auto-generated sections from directory structure, and custom ordering. The config is fully typed so your editor gives you autocomplete for every option.

astro.config.mjstypescript

// astro.config.mjs
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  integrations: [
    starlight({
      title: "My Project Docs",
      social: {
        github: "https://github.com/you/my-project",
      },
      sidebar: [
        {
          label: "Getting Started",
          items: [
            { label: "Introduction", slug: "getting-started/introduction" },
            { label: "Installation", slug: "getting-started/installation" },
            { label: "Quick Start", slug: "getting-started/quick-start" },
          ],
        },
        {
          label: "Guides",
          autogenerate: { directory: "guides" },
        },
        {
          label: "API Reference",
          autogenerate: { directory: "api" },
        },
      ],
      customCss: ["./src/styles/custom.css"],
    }),
  ],
});

Tip: Use autogenerate for sections that grow frequently (like guides) and manual items for fixed pages (like getting started).

Tip: Add a customCss file from the start — you'll inevitably want to tweak colors or spacing.

Write Your First Documentation Pages

Create MDX documentation pages with frontmatter for title, description, and sidebar ordering. Starlight automatically generates a table of contents from your headings, adds syntax highlighting to code blocks, and creates navigation links between pages. Use clear, scannable headings and short paragraphs.

src/content/docs/getting-started/installation.mdxmarkdown

---
title: Installation
description: How to install and set up My Project in your codebase.
---

## Prerequisites

Make sure you have Node.js 20 or later installed:

```bash
node --version
```

## Install the Package

```bash
npm install my-project
```

## Configuration

Create a config file at the root of your project:

```typescript title="my-project.config.ts"
import { defineConfig } from "my-project";

export default defineConfig({
  output: "./dist",
  plugins: [],
});
```

:::tip
You can also use a `.json` or `.yaml` config file if you prefer.
:::

:::caution
Make sure your Node.js version is 20+ or the CLI will fail silently.
:::

Tip: Use the title attribute on code blocks (```typescript title="filename.ts") to show the filename above the snippet.

Tip: Starlight's :::tip, :::caution, and :::danger callouts draw attention to important information without custom components.

Add Custom Components for Interactive Examples

Extend your docs with custom Astro components for interactive API examples, tabbed content, or live code playgrounds. Starlight supports MDX natively, so you can import and use any Astro or React component directly in your documentation pages. This is powerful for showing API responses or configuration options.

src/components/ApiExample.astroastro

---
// src/components/ApiExample.astro
interface Props {
  method: "GET" | "POST" | "PUT" | "DELETE";
  endpoint: string;
  response: string;
}

const { method, endpoint, response } = Astro.props;

const methodColors: Record<string, string> = {
  GET: "bg-green-500/10 text-green-400 border-green-500/30",
  POST: "bg-blue-500/10 text-blue-400 border-blue-500/30",
  PUT: "bg-yellow-500/10 text-yellow-400 border-yellow-500/30",
  DELETE: "bg-red-500/10 text-red-400 border-red-500/30",
};
---

<div class="not-content my-4 rounded-lg border border-gray-700 overflow-hidden">
  <div class="flex items-center gap-3 border-b border-gray-700 bg-gray-800/50 px-4 py-2">
    <span class={`rounded px-2 py-0.5 text-xs font-mono font-bold border ${methodColors[method]}`}>
      {method}
    </span>
    <code class="text-sm text-gray-300">{endpoint}</code>
  </div>
  <pre class="m-0 overflow-x-auto p-4 text-sm">
    <code>{response}</code>
  </pre>
</div>

Tip: Wrap custom components in a 'not-content' class to prevent Starlight's prose styles from interfering with your layout.

Tip: Keep interactive components small and focused — docs should be readable without JavaScript enabled.

Enable Full-Text Search

Starlight includes Pagefind for client-side full-text search out of the box — no configuration needed. Pagefind builds a search index at build time and loads it lazily when the user opens the search dialog. It works entirely in the browser with no server or third-party service required.

astro.config.mjstypescript

// astro.config.mjs — search is enabled by default
// To customize, pass options to the pagefind config:
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  integrations: [
    starlight({
      title: "My Project Docs",
      pagefind: true, // enabled by default
      // To exclude pages from search:
      // Add `pagefind: false` to any page's frontmatter
    }),
  ],
});

Tip: Search only works in production builds (npm run build && npm run preview) — it won't work in dev mode.

Tip: Add pagefind: false to changelog or release note pages that would clutter search results.

Deploy to Vercel or Netlify

Deploy your documentation site as a static build. Astro outputs plain HTML files that can be hosted anywhere. Vercel and Netlify both auto-detect Astro projects and configure the build command for you. Every push to your main branch triggers a new deployment with your latest docs.

bash

# Build locally to verify
npm run build
npm run preview

# Push to GitHub
git init
git add .
git commit -m "Initial documentation site"
gh repo create my-docs --public --push

# Deploy to Vercel (auto-detects Astro)
npm install -g vercel
vercel --prod

# Or deploy to Netlify
# Just connect your GitHub repo in the Netlify dashboard
# Build command: npm run build
# Publish directory: dist/

Tip: Set up a custom domain like docs.yourproject.com for a professional appearance.

Tip: Enable branch previews so pull requests automatically generate preview documentation sites for review.

Next Steps

→Add versioned documentation using Starlight's built-in version dropdown support.
→Set up i18n to translate your docs into multiple languages with Starlight's locale system.
→Add an OpenAPI reference page using the starlight-openapi integration for auto-generated API docs.
→Configure GitHub Actions to run link checking and spell checking on every pull request.