starlight-base

Starlight Base Setup

Starlight is a full-featured documentation theme built on Astro. It ships with routing, search, dark mode, i18n, and accessibility — configure features rather than build them.

When to Use

• Creating a new documentation site with Astro and Starlight
• Adding Starlight to an existing Astro project
• Configuring core options (logo, sidebar, social links, etc.)
• Setting up content pages and navigation

When Not to Use

• Custom theming with CSS variables or Tailwind — use starlight-theme instead
• Overriding built-in Starlight components — use starlight-custom-component instead

Mindset

Starlight = Astro integration + file-based routing + content collections.

1. One integration, one config object. All options live inside starlight({}) in astro.config.mjs. No separate config file.
2. Files are pages. Every .md / .mdx under src/content/docs/ becomes a URL. File path = URL route.
3. Sidebar and routing are independent. You can have a page with no sidebar entry, or a sidebar entry for any slug. They are not coupled unless you use autogenerate.

Quick Start

npm create astro@latest -- --template starlight
npm run dev

To add Starlight to an existing Astro project:

npx astro add starlight

Core Configuration

All options live inside starlight({}). See configuration-reference.md for the full option table.

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

export default defineConfig({
  site: 'https://mydocs.example.com', // Required for sitemap
  integrations: [
    starlight({
      title: 'My Docs',
      logo: { src: './src/assets/logo.svg' },
      social: [
        { icon: 'github', label: 'GitHub', href: 'https://github.com/my-org/repo' },
      ],
      sidebar: [
        {
          label: 'Guides',
          items: [
            { label: 'Getting Started', slug: 'guides/getting-started' },
          ],
        },
        { label: 'Reference', autogenerate: { directory: 'reference' } },
      ],
      editLink: { baseUrl: 'https://github.com/my-org/repo/edit/main/docs/' },
      customCss: ['./src/styles/custom.css'],
    }),
  ],
});