Starlight Docs Sites

What is Starlight?

Starlight is a full-featured documentation theme built on Astro. It provides:

• Sidebar navigation with auto-generation
• Search (powered by Pagefind)
• i18n support
• Dark/light mode
• Built-in components (cards, tabs, asides)

Quick Setup

npm create astro@latest -- --template starlight

Configuration

astro.config.mjs

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      social: [
        { icon: 'github', label: 'GitHub', href: 'https://github.com/...' },
      ],
      sidebar: [
        {
          label: 'Getting Started',
          items: [
            { label: 'Installation', slug: 'getting-started/installation' },
            { label: 'Quick Start', slug: 'getting-started/quick-start' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    }),
  ],
});

Content Structure

src/content/docs/
  index.mdx              # Home page
  getting-started/
    installation.md
    quick-start.md
  guides/
    routing.md
    deployment.md
  reference/
    api.md               # Auto-generated sidebar picks these up
    config.md

Sidebar Configuration

Manual Items

sidebar: [
  {
    label: 'Guides',
    items: [
      { label: 'Getting Started', slug: 'guides/getting-started' },
      { label: 'Advanced', slug: 'guides/advanced' },
    ],
  },
]

Auto-Generated from Directory

sidebar: [
  {
    label: 'Reference',
    autogenerate: { directory: 'reference' },
  },
]

Collapsed Groups

sidebar: [
  {
    label: 'Advanced',
    collapsed: true,
    items: [/* ... */],
  },
]

External Links

sidebar: [
  {
    label: 'Resources',
    items: [
      { label: 'Astro Docs', link: 'https://docs.astro.build' },
    ],
  },
]

Gotchas

link and items are mutually exclusive

A sidebar group cannot have both a link property AND an items array — this causes a build error. To make a category clickable, create an index.md inside the directory and include it as the first item.

sidebar: [
  {
    label: 'Guides',
    // WRONG: Cannot combine link + items
    // link: '/guides/',
    // items: [...]

    // CORRECT: Use index page as first item
    items: [
      { label: 'Overview', slug: 'guides' },  // points to guides/index.md
      { label: 'Getting Started', slug: 'guides/getting-started' },
    ],
  },
]

• autogenerate doesn’t create index pages: If you use autogenerate: { directory: 'guides' }, it picks up files in that directory but won’t generate an overview page. Create an index.md manually.
• Ordering in autogenerated groups: Use sidebar.order in page frontmatter to control the order within autogenerated groups.

Page Frontmatter

---
title: My Page Title
description: A description for SEO and social sharing.
sidebar:
  order: 2           # Manual ordering within auto-generated groups
  label: Custom Label # Override the title in sidebar
  badge:
    text: New
    variant: tip     # tip | note | danger | caution | success
  hidden: false      # Hide from sidebar but keep accessible
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 4
---

Built-in Components

Cards and LinkCards

import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';

{/* Card = display-only, does NOT support href */}
<CardGrid>
  <Card title="Feature One" icon="rocket">
    Description as children content.
  </Card>
  <Card title="Feature Two" icon="puzzle">
    Description as children content.
  </Card>
</CardGrid>

{/* LinkCard = clickable, takes href + description as PROPS (not children) */}
<CardGrid>
  <LinkCard title="Getting Started" href="/guides/getting-started/" description="Learn setup" />
  <LinkCard title="Configuration" href="/reference/configuration/" description="Config options" />
</CardGrid>

Tip

Use LinkCard when you need clickable cards. Card has no href prop. Note that LinkCard takes description as a prop, not as children content.

Tabs

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="npm">
    ```bash
    npm install astro
    ```
  </TabItem>
  <TabItem label="pnpm">
    ```bash
    pnpm add astro
    ```
  </TabItem>
</Tabs>

Asides (Callouts)

:::note
This is a note.
:::

:::tip
This is a helpful tip.
:::

:::caution
Be careful with this.
:::

:::danger
This could break things!
:::

Steps

import { Steps } from '@astrojs/starlight/components';

<Steps>
1. Install the package
2. Configure the settings
3. Deploy your site
</Steps>

i18n

starlight({
  title: 'My Docs',
  defaultLocale: 'en',
  locales: {
    en: { label: 'English' },
    es: { label: 'Español', lang: 'es' },
    fr: { label: 'Français', lang: 'fr' },
  },
}),

Content structure for i18n:

src/content/docs/
  en/
    index.md
    guides/...
  es/
    index.md
    guides/...

Customization

Custom CSS

starlight({
  customCss: ['./src/styles/custom.css'],
}),

Override Components

starlight({
  components: {
    Header: './src/components/CustomHeader.astro',
    Footer: './src/components/CustomFooter.astro',
  },
}),

Updating Starlight

npx @astrojs/upgrade