Why Starlight?

Starlight is Astro’s official documentation theme, purpose-built for creating beautiful, accessible, and high-performance documentation sites. While Astro provides the performance foundation, Starlight adds all the features developers expect from modern documentation.

Built Exclusively for Documentation

Documentation-First Design

Unlike general-purpose themes adapted for docs, Starlight was designed from day one for technical documentation:

// Every feature is documentation-focused
✓ Automatic sidebar generation from file structure
✓ Built-in search (no configuration)
✓ Dark mode (respects system preference)
✓ Mobile navigation
✓ Table of contents on every page
✓ Previous/Next navigation
✓ Edit this page links
✓ Syntax highlighting
✓ Frontmatter schema validation

Comparison: General Theme vs Starlight

Feature	General Theme	Starlight
Sidebar	Manual config	Auto-generated
Search	Plugin needed	Built-in (Pagefind)
Dark mode	Custom CSS	Built-in
Mobile nav	Custom implementation	Built-in
i18n	Manual setup	Configuration-driven
Accessibility	Varies	WCAG 2.1 AA compliant
TOC	Plugin or custom	Automatic

Zero Configuration Defaults

Starlight works beautifully out of the box:

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      // That's it! Everything else has sensible defaults
    }),
  ],
});

What You Get Immediately:

• Responsive layout (mobile, tablet, desktop)
• Dark mode toggle
• Automatic sidebar from file structure
• Search functionality
• Syntax highlighting
• Previous/Next navigation
• Social links support
• Custom logo support

Internationalization (i18n)

Multi-Language Support

Starlight makes internationalization simple with built-in RTL support, language switcher, and translated UI:

astro.config.mjs

starlight({
  title: 'My Docs',
  defaultLocale: 'en',
  locales: {
    en: {
      label: 'English',
    },
    es: {
      label: 'Español',
    },
    fr: {
      label: 'Français',
    },
    ar: {
      label: 'العربية',
      dir: 'rtl', // Right-to-left support
    },
    ja: {
      label: '日本語',
    },
    zh: {
      label: '简体中文',
    },
  },
}),

File Structure for i18n:

src/content/docs/
├── en/
│   ├── index.md
│   └── guide.md
├── es/
│   ├── index.md
│   └── guide.md
└── fr/
    ├── index.md
    └── guide.md

# URLs generated automatically:
# /           → English (default)
# /es/        → Spanish
# /fr/        → French

Translated UI Components

Starlight translates all UI elements automatically:

Language	”On this page"	"Search"	"Edit page”	Support Status
English	On this page	Search	Edit page	✅ Built-in
Spanish	En esta página	Buscar	Editar página	✅ Built-in
French	Sur cette page	Rechercher	Modifier la page	✅ Built-in
German	Auf dieser Seite	Suchen	Seite bearbeiten	✅ Built-in
Japanese	このページについて	検索	ページを編集	✅ Built-in
Arabic	على هذه الصفحة	بحث	تحرير الصفحة	✅ Built-in
Chinese	本页内容	搜索	编辑页面	✅ Built-in
Custom	your translation	your translation	your translation	✅ Configurable

Custom Translations:

src/content/config.ts

import { defineCollection } from 'astro:content';

export const collections = {
  i18n: defineCollection({
    type: 'data',
    schema: z.object({
      'page.editLink': z.string(),
      'page.lastUpdated': z.string(),
      // ... customize any UI string
    }),
  }),
};

Language Switcher

Automatically generated language picker:

---
// Automatic language detection
// Shows languages where current page exists
---

<!-- Language switcher in header -->
<!-- Detects browser language preference -->
<!-- Remembers user selection in localStorage -->
<!-- Switches to equivalent page in new language -->

:::tip SEO Benefit Starlight automatically adds hreflang tags for all language variants, helping search engines understand your multi-language content:

<link rel="alternate" hreflang="en" href="/guide/" />
<link rel="alternate" hreflang="es" href="/es/guide/" />
<link rel="alternate" hreflang="fr" href="/fr/guide/" />

:::

Built-in Search

Pagefind Integration

Starlight includes Pagefind, a static search library that requires zero server infrastructure:

// No configuration needed!
// Search is automatically available

// Optional customization:
starlight({
  title: 'My Docs',
  search: {
    provider: 'pagefind',
  },
  // Or use Algolia DocSearch:
  // search: {
  //   provider: 'algolia',
  //   appId: 'YOUR_APP_ID',
  //   apiKey: 'YOUR_SEARCH_KEY',
  //   indexName: 'YOUR_INDEX_NAME',
  // },
}),

Pagefind Features:

• Instant search: No API calls, indexes built at build time
• Multi-language: Automatically indexes all language variants
• Fuzzy matching: Finds results even with typos
• Excerpt highlighting: Shows search term context
• Keyboard navigation: Full keyboard accessibility
• Mobile-optimized: Works perfectly on mobile devices

Search Performance:

Metric	Pagefind (Static)	Algolia (API)
Initial load	0 KB	45 KB (SDK)
Search latency	~50ms (local)	~200ms (network)
Offline support	✅ Yes	❌ No
Cost (1M searches)	$0 (static)	$1-50 (API calls)
Privacy	✅ No tracking	⚠️ Sends queries to Algolia

Search Customization

// Customize search behavior
starlight({
  pagefind: {
    // Exclude content from search
    exclude: ['/api-internal/**', '/draft/**'],

    // Boost certain content
    ranking: {
      pageRank: true,
      termFrequency: true,
    },

    // Multi-language configuration
    languages: {
      en: 'english',
      es: 'spanish',
      fr: 'french',
    },
  },
}),

Excluding Content from Search:

---
title: Internal Documentation
# Exclude this page from search results
pagefind: false
---

This page won't appear in search results.

Mobile-First Design

Responsive Layout

Starlight is designed mobile-first, ensuring documentation works perfectly on all devices:

/* Mobile (320px - 768px) */
- Single column layout
- Hamburger menu navigation
- Collapsible table of contents
- Touch-optimized hit areas (44px minimum)
- No horizontal scroll

/* Tablet (768px - 1024px) */
- Two column layout (sidebar + content)
- Expandable sidebar
- Inline table of contents
- Swipe gestures for navigation

/* Desktop (1024px+) */
- Three column layout (sidebar + content + TOC)
- Persistent sidebar
- Fixed table of contents
- Keyboard shortcuts

Mobile Navigation:

┌─────────────────────┐
│ [☰] My Docs    [🔍] │  ← Hamburger menu + search
├─────────────────────┤
│                     │
│   Content area      │
│   (full width)      │
│                     │
│   [▼ On this page]  │  ← Collapsible TOC
│   • Introduction    │
│   • Installation    │
│                     │
└─────────────────────┘

Touch-Optimized

All interactive elements meet accessibility standards:

Element	Minimum Size	Starlight Size
Buttons	44x44px	48x48px ✅
Links	44x44px	48x24px ✅
Menu items	44x44px	52x44px ✅
Toggle switches	44x44px	48x28px ✅

Performance on Mobile Networks

Starlight is optimized for slow connections:

Network	Time to Interactive
4G (fast)	0.3s
3G (regular)	0.9s
2G (slow)	2.4s
Offline	Works (service worker)

Note

Most documentation sites take 8-15 seconds on 2G networks. Starlight’s static HTML approach makes it 6x faster.

Accessibility (WCAG 2.1 AA)

Built-in Accessibility

Starlight meets WCAG 2.1 Level AA standards out of the box:

Keyboard Navigation:

Tab          → Next interactive element
Shift+Tab    → Previous interactive element
/            → Focus search
Esc          → Close search/menu
Arrow keys   → Navigate search results
Enter        → Activate link/button

Screen Reader Support:

• Semantic HTML5 landmarks (<nav>, <main>, <aside>)
• ARIA labels for interactive elements
• Skip to content link
• Heading hierarchy (never skip levels)
• Alt text for all images
• Form labels and error messages

Color Contrast

All text meets WCAG AA contrast requirements:

Element	Light Mode	Dark Mode	Ratio
Body text	#1a1a1a on #ffffff	#e8e8e8 on #1a1a1a	14.5:1 ✅
Headings	#000000 on #ffffff	#ffffff on #1a1a1a	21:1 ✅
Links	#0066cc on #ffffff	#4da3ff on #1a1a1a	7.2:1 ✅
Code	#24292e on #f6f8fa	#e6edf3 on #0d1117	10.8:1 ✅

:::tip Accessibility Testing Starlight passes automated accessibility tests:

• axe DevTools: 0 violations
• Lighthouse Accessibility: 100/100
• WAVE: 0 errors :::

Focus Management

Visible focus indicators for keyboard navigation:

/* Starlight's focus styles */
:focus-visible {
  outline: 2px solid var(--sl-color-accent);
  outline-offset: 2px;
  border-radius: 4px;
}

/* Never removes focus indicators */
/* Always visible for keyboard users */
/* Hidden for mouse users (:focus-visible) */

Dark Mode

System Preference Detection

Starlight respects the user’s system preference:

// Automatic dark mode detection
// No configuration needed

// User preference hierarchy:
// 1. User's manual selection (stored in localStorage)
// 2. System preference (prefers-color-scheme: dark)
// 3. Default theme (light)

Dark Mode Toggle:

---
// Automatic theme switcher in header
// Three states:
// - Light
// - Dark
// - Auto (follow system)
---

<!-- No flash of wrong theme -->
<!-- Preference saved in localStorage -->
<!-- Syncs across tabs -->

Dark Mode Colors

Carefully crafted color palette for readability:

Element	Light Mode	Dark Mode
Background	#ffffff	#1a1a1a
Surface	#f8f9fa	#2d2d2d
Text	#1a1a1a	#e8e8e8
Accent	#0066cc	#4da3ff
Border	#e0e0e0	#404040
Code block	#f6f8fa	#0d1117

Syntax Highlighting

Dual themes for code blocks:

// Light mode: GitHub Light
// Dark mode: GitHub Dark

// Automatically switches with theme
// No flash of unstyled content
// Respects user's choice

const example = 'Looks great in both themes!';

Supported Themes:

Light Theme	Dark Theme	Language Support
GitHub Light	GitHub Dark	100+ languages
Solarized Light	Solarized Dark	100+ languages
Material Light	Material Palenight	100+ languages
Custom	Custom	Fully customizable

Customization

Theme Configuration

Extensive customization without touching CSS:

astro.config.mjs

starlight({
  title: 'My Documentation',
  logo: {
    src: './src/assets/logo.svg',
    replacesTitle: true,
  },
  customCss: [
    './src/styles/custom.css',
  ],
  head: [
    {
      tag: 'link',
      attrs: {
        rel: 'icon',
        href: '/favicon.svg',
        type: 'image/svg+xml',
      },
    },
  ],
  social: {
    github: 'https://github.com/yourusername/yourrepo',
    twitter: 'https://twitter.com/yourusername',
    discord: 'https://discord.gg/yourinvite',
    youtube: 'https://youtube.com/@yourchannel',
  },
  editLink: {
    baseUrl: 'https://github.com/yourusername/yourrepo/edit/main/',
  },
  lastUpdated: true,
  pagination: true,
  favicon: '/favicon.svg',
  titleDelimiter: '|',
  disable404Route: false,
  components: {
    // Override components (use sparingly)
    Head: './src/components/CustomHead.astro',
  },
}),

CSS Custom Properties

Customize colors with CSS variables:

src/styles/custom.css

:root {
  /* Brand colors */
  --sl-color-accent: #2563eb;
  --sl-color-accent-high: #1e40af;

  /* Typography */
  --sl-font: 'Inter', system-ui, sans-serif;
  --sl-font-mono: 'JetBrains Mono', monospace;

  /* Spacing */
  --sl-content-width: 45rem;
  --sl-sidebar-width: 18rem;

  /* Border radius */
  --sl-border-radius: 0.5rem;
}

/* Dark mode overrides */
:root[data-theme='dark'] {
  --sl-color-accent: #60a5fa;
  --sl-color-accent-high: #93c5fd;
}

Customizable Properties:

Category	Variables	Use Case
Colors	40+ variables	Brand colors, backgrounds
Typography	12+ variables	Fonts, sizes, line heights
Spacing	15+ variables	Margins, padding, gaps
Layout	8+ variables	Widths, breakpoints
Borders	6+ variables	Radius, thickness, colors

Component Overrides

Override individual components while keeping the rest:

src/components/CustomHeader.astro

---
import type { Props } from '@astrojs/starlight/props';

// Extend default header
// Add custom navigation, banners, etc.
---

<header>
  <div class="custom-banner">
    📢 New version 2.0 released!
  </div>
  <slot /> <!-- Original header content -->
</header>

:::caution Component Override Warning Our optimizer package avoids component overrides because they can break easily with Starlight updates. Prefer CSS customization and script injection when possible. :::

Sidebar Navigation

Automatic Generation

Starlight generates sidebar from your file structure:

src/content/docs/
├── index.md               → Homepage (not in sidebar)
├── getting-started.md     → "Getting Started"
├── guides/
│   ├── installation.md    → "Installation" (under "Guides")
│   └── configuration.md   → "Configuration" (under "Guides")
└── reference/
    ├── api.md             → "API" (under "Reference")
    └── cli.md             → "CLI" (under "Reference")

Generated Sidebar:

Getting Started
Guides
  ├─ Installation
  └─ Configuration
Reference
  ├─ API
  └─ CLI

Manual Sidebar Control

Fine-tune sidebar with frontmatter:

---
title: Installation Guide
sidebar:
  label: Install  # Custom label
  order: 1        # Position in sidebar
  badge: New      # Badge (text or variant)
  hidden: false   # Hide from sidebar
  attrs:
    class: highlight  # Custom CSS class
---

Badge Variants:

Badge Type	Appearance	Use Case
badge: "New"	Blue badge	New content
badge: {text: "Beta", variant: "caution"}	Yellow badge	Beta features
badge: {text: "Deprecated", variant: "danger"}	Red badge	Deprecated APIs
badge: {text: "Pro", variant: "success"}	Green badge	Premium content

Grouped Sidebar

Organize sidebar into collapsible groups:

astro.config.mjs

starlight({
  sidebar: [
    {
      label: 'Getting Started',
      items: [
        { label: 'Introduction', link: '/intro/' },
        { label: 'Installation', link: '/install/' },
      ],
    },
    {
      label: 'Guides',
      collapsed: false, // Expanded by default
      autogenerate: { directory: 'guides' },
    },
    {
      label: 'Reference',
      collapsed: true, // Collapsed by default
      items: [
        { label: 'API', link: '/api/' },
        { label: 'CLI', link: '/cli/' },
      ],
    },
  ],
}),

Table of Contents

Automatic TOC Generation

Every page gets an automatic table of contents:

---
title: API Reference
# TOC is automatically generated from headings
---

# API Reference          ← Not in TOC (h1 is page title)

## Authentication       ← In TOC
### API Keys            ← In TOC (if depth allows)
### OAuth 2.0           ← In TOC

## Endpoints            ← In TOC
### GET /users          ← In TOC

TOC Configuration:

astro.config.mjs

starlight({
  tableOfContents: {
    minHeadingLevel: 2, // Start at h2
    maxHeadingLevel: 3, // End at h3
  },
}),

Per-Page TOC Control:

---
title: Simple Page
tableOfContents: false  # Hide TOC for this page
---

Scroll Spy

Active heading highlighted as you scroll:

// Automatic scroll spy
// Highlights current section in TOC
// Smooth scroll to headings on click
// Deep linking with hash URLs

Content Features

Callouts and Admonitions

Built-in callout blocks for important information:

:::note
This is a note callout. Use for general information.
:::

:::tip
This is a tip callout. Use for helpful advice.
:::

:::caution
This is a caution callout. Use for warnings.
:::

:::danger
This is a danger callout. Use for critical warnings.
:::

Custom Titles:

:::tip[Pro Tip]
You can customize the callout title!
:::

Code Blocks

Syntax highlighting for 100+ languages:

```javascript title="example.js" {3-5}
// Line 1
// Line 2
// Lines 3-5 are highlighted
const highlighted = true;
console.log('This line is highlighted');
// Line 6
```

Code Block Features:

• Line highlighting
• Filename labels
• Diff syntax (+/-)
• Line numbers (optional)
• Copy button
• Language icons

File Tree Component

Display file structures:

<FileTree>
- src/
  - components/
    - Header.astro
    - Footer.astro
  - pages/
    - index.astro
- package.json
</FileTree>

Performance Benefits

Build Performance

Starlight is optimized for fast builds:

Pages	Build Time	Incremental
100	12s	0.3s
500	45s	0.4s
1000	2m 18s	0.5s
5000	9m 42s	0.6s

Runtime Performance

Lighthouse scores for Starlight sites:

Metric	Score
Performance	100
Accessibility	100
Best Practices	100
SEO	100

Bundle Size:

Initial HTML: 14 KB
CSS: 8 KB (includes dark mode)
JavaScript: 4 KB (search + theme toggle)
Total: 26 KB

Compare to typical docs site:
Initial HTML: 85 KB
CSS: 45 KB
JavaScript: 245 KB
Total: 375 KB (14x larger)

Conclusion

Starlight provides everything you need for world-class documentation:

✅ Zero configuration: Works beautifully out of the box ✅ Multi-language: i18n with RTL support ✅ Built-in search: No external dependencies ✅ Mobile-first: Perfect on any device ✅ Accessible: WCAG 2.1 AA compliant ✅ Dark mode: Respects user preference ✅ Customizable: Extensive theming options ✅ Fast: 100/100 Lighthouse scores

When combined with Astro’s performance benefits and our optimizer package, you get the ultimate documentation platform.

---

Next Steps:

• Learn why the optimizer package is needed
• Explore analytics and GDPR features
• Get started with configuration