Fix: Starlight Not Working — Pages Not Rendering, Sidebar Wrong, or Custom Components Broken

The Problem

Starlight pages return 404:

GET /guides/getting-started → 404 Not Found

Or the sidebar doesn’t match your file structure:

Sidebar shows files in alphabetical order instead of custom order

Or custom components don’t render in MDX:

import { Card } from '@astrojs/starlight/components';
<Card title="Hello">Content</Card>
<!-- Renders as plain text -->

Why This Happens

Starlight is Astro’s official documentation theme. It builds on Astro’s content collections:

• Docs must be in src/content/docs/ — Starlight reads .md and .mdx files from this specific directory. Files elsewhere aren’t recognized.
• Sidebar is auto-generated or manually configured — by default, Starlight creates sidebar entries from the file structure. Manual sidebar config in astro.config.mjs overrides auto-generation, and typos in slugs cause missing entries.
• Starlight has its own built-in components — Card, Tabs, Aside etc. come from @astrojs/starlight/components. Using generic Astro components or importing from the wrong path causes rendering issues.
• Frontmatter controls page metadata — title is required. Missing it causes build errors. sidebar frontmatter overrides the global sidebar config for that page.

Fix 1: Setup Starlight

npm create astro@latest -- --template starlight
# Or add to existing Astro project:
npx astro add starlight

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      logo: {
        src: './src/assets/logo.svg',
        alt: 'My Project',
      },

      // Social links
      social: {
        github: 'https://github.com/user/repo',
        discord: 'https://discord.gg/xxx',
      },

      // Sidebar configuration
      sidebar: [
        {
          label: 'Getting Started',
          items: [
            { label: 'Introduction', slug: 'guides/introduction' },
            { label: 'Installation', slug: 'guides/installation' },
            { label: 'Quick Start', slug: 'guides/quick-start' },
          ],
        },
        {
          label: 'Core Concepts',
          autogenerate: { directory: 'concepts' },
          // Auto-generates from src/content/docs/concepts/
        },
        {
          label: 'API Reference',
          collapsed: true,  // Collapsed by default
          autogenerate: { directory: 'api' },
        },
        {
          label: 'Resources',
          items: [
            { label: 'GitHub', link: 'https://github.com/user/repo', attrs: { target: '_blank' } },
            { label: 'Changelog', slug: 'changelog' },
          ],
        },
      ],

      // Custom CSS
      customCss: ['./src/styles/custom.css'],

      // Default language
      defaultLocale: 'en',

      // Search
      pagefind: true,  // Built-in search (default)

      // Edit link
      editLink: {
        baseUrl: 'https://github.com/user/repo/edit/main/',
      },

      // Table of contents
      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 },

      // Head tags
      head: [
        { tag: 'meta', attrs: { property: 'og:type', content: 'website' } },
      ],
    }),
  ],
});

Fix 2: Content Structure and Frontmatter

src/content/docs/
├── index.mdx                    # /
├── guides/
│   ├── introduction.mdx         # /guides/introduction
│   ├── installation.mdx         # /guides/installation
│   └── quick-start.mdx          # /guides/quick-start
├── concepts/
│   ├── architecture.mdx         # /concepts/architecture
│   └── configuration.mdx        # /concepts/configuration
├── api/
│   ├── client.mdx               # /api/client
│   └── server.mdx               # /api/server
└── changelog.mdx                # /changelog

---
title: Installation Guide
description: How to install and set up the project
sidebar:
  order: 2            # Manual ordering within auto-generated groups
  badge:
    text: New
    variant: tip       # note | tip | caution | danger
  # label: Custom Label  # Override sidebar label
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 4
---

# Installation Guide

Follow these steps to install the project.

## Prerequisites

You need Node.js 18 or higher.

## Install

```bash
npm install my-package

```mdx
---
title: Advanced Configuration
description: Deep dive into configuration options
sidebar:
  order: 5
  badge: Advanced
---

Content here...

Fix 3: Built-In Components

---
title: Component Examples
---

import { Card, CardGrid, Aside, Tabs, TabItem, LinkCard, Steps, Badge, Icon, FileTree } from '@astrojs/starlight/components';

## Cards

<CardGrid>
  <Card title="Quick Start" icon="rocket">
    Get up and running in 5 minutes.
  </Card>
  <Card title="API Reference" icon="document">
    Complete API documentation.
  </Card>
  <Card title="Examples" icon="puzzle">
    Real-world usage examples.
  </Card>
</CardGrid>

<LinkCard title="View on GitHub" href="https://github.com/user/repo" description="Star us on GitHub!" />

## Asides (Callouts)

<Aside>This is a note.</Aside>

<Aside type="tip">This is a helpful tip!</Aside>

<Aside type="caution">Be careful with this.</Aside>

<Aside type="danger">This could break your app!</Aside>

## Tabs

<Tabs>
  <TabItem label="npm">
    ```bash
    npm install my-package
    ```
  </TabItem>
  <TabItem label="pnpm">
    ```bash
    pnpm add my-package
    ```
  </TabItem>
  <TabItem label="yarn">
    ```bash
    yarn add my-package
    ```
  </TabItem>
</Tabs>

## Steps

<Steps>
1. Install the package

   ```bash
   npm install my-package

2. Create a configuration file

   Create config.ts in your project root.

3. Start the dev server

   npm run dev

File Tree

Badges

DefaultNoteTipCautionDanger

## Fix 4: Custom Overrides

```typescript
// astro.config.mjs — override Starlight components
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      components: {
        // Override the header
        Header: './src/components/CustomHeader.astro',
        // Override the footer
        Footer: './src/components/CustomFooter.astro',
        // Override the page sidebar
        // Sidebar: './src/components/CustomSidebar.astro',
      },
    }),
  ],
});

<!-- src/components/CustomHeader.astro -->
---
import Default from '@astrojs/starlight/components/Header.astro';
---

<!-- Extend the default header -->
<Default {...Astro.props}>
  <div slot="after">
    <a href="https://github.com/user/repo" class="github-badge">
      ⭐ Star on GitHub
    </a>
  </div>
</Default>

<style>
  .github-badge {
    background: #333;
    color: white;
    padding: 4px 12px;
    border-radius: 20px;
    font-size: 0.8rem;
    text-decoration: none;
  }
</style>

/* src/styles/custom.css — customize Starlight's CSS variables */
:root {
  --sl-color-accent-low: #1e1b4b;
  --sl-color-accent: #4f46e5;
  --sl-color-accent-high: #c7d2fe;
  --sl-color-white: #ffffff;
  --sl-color-gray-1: #f8fafc;
  --sl-color-gray-2: #e2e8f0;
  --sl-color-gray-3: #94a3b8;
  --sl-color-gray-4: #475569;
  --sl-color-gray-5: #1e293b;
  --sl-color-gray-6: #0f172a;
  --sl-color-black: #020617;

  --sl-font: 'Inter', sans-serif;
  --sl-font-mono: 'Fira Code', monospace;
}

/* Custom sidebar width */
:root {
  --sl-sidebar-width: 280px;
}

/* Style code blocks */
.sl-markdown-content pre {
  border-radius: 8px;
  border: 1px solid var(--sl-color-gray-5);
}

Fix 5: Internationalization (i18n)

// astro.config.mjs — multi-language docs
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      defaultLocale: 'en',
      locales: {
        en: { label: 'English' },
        ja: { label: '日本語', lang: 'ja' },
        es: { label: 'Español', lang: 'es' },
      },
      sidebar: [
        {
          label: 'Guides',
          translations: {
            ja: 'ガイド',
            es: 'Guías',
          },
          autogenerate: { directory: 'guides' },
        },
      ],
    }),
  ],
});

src/content/docs/
├── en/
│   └── guides/
│       └── getting-started.mdx
├── ja/
│   └── guides/
│       └── getting-started.mdx
└── es/
    └── guides/
        └── getting-started.mdx

Fix 6: Plugins and Extensions

# Starlight plugins
npm install starlight-links-validator  # Check for broken links
npm install starlight-blog             # Add a blog

// astro.config.mjs
import starlightLinksValidator from 'starlight-links-validator';
import starlightBlog from 'starlight-blog';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightLinksValidator(),
        starlightBlog({
          title: 'Blog',
          authors: {
            alice: { name: 'Alice', title: 'Lead Dev', picture: '/authors/alice.jpg' },
          },
        }),
      ],
    }),
  ],
});

Still Not Working?

Pages return 404 — docs must be in src/content/docs/. The URL path mirrors the file path: src/content/docs/guides/intro.mdx → /guides/intro. Check for typos in filenames and ensure the file has valid frontmatter with at least a title field.

Sidebar order is wrong — auto-generated sidebars sort alphabetically by default. Use sidebar.order in frontmatter to control ordering within a group. Lower numbers appear first. Or switch to manual sidebar config in astro.config.mjs.

Components import fails — Starlight components must be imported from @astrojs/starlight/components. Using import { Card } from 'astro' or other paths won’t work. Make sure the file is .mdx (not .md) to use imports.

Custom CSS doesn’t apply — add the CSS file path to customCss array in the Starlight config. CSS variables must use Starlight’s variable names (prefixed --sl-). Inspect the page to find the correct variable names.

For related documentation issues, see Fix: Nextra Not Working and Fix: Docusaurus Not Working.