Skip to content
Lumen Docs

Configuration

Lumen offers many configuration options to adapt your documentation to your needs. All options are in the astro.config.mjs file, under the starlight() key.

Title and Description

Section titled “Title and Description”

Start by defining your site’s identity:

starlight({
  title: 'MyProject Documentation',
  description: 'Everything you need to know to use MyProject.',
});

The title appears in the header of every page and in the browser tab. The description is used for SEO.

Section titled “Logo”

Replace the text title with a custom logo:

starlight({
  logo: {
    src: './src/assets/logo.svg',
    alt: 'MyProject Logo',
  },
});

Place your file in src/assets/ and reference it with a relative path.

Section titled “Sidebar”

Organize your documentation with a custom sidebar:

starlight({
  sidebar: [
    {
      label: 'Guides',
      items: [
        { label: 'Quick Start', slug: 'docs/guides/getting-started' },
        { label: 'Installation', slug: 'docs/guides/installation' },
        { label: 'Configuration', slug: 'docs/guides/configuration' },
      ],
    },
    {
      label: 'Reference',
      items: [
        { label: 'API', slug: 'docs/reference/api' },
        { label: 'Options', slug: 'docs/reference/configuration-options' },
        { label: 'CLI', slug: 'docs/reference/cli' },
      ],
    },
  ],
});

Each entry has a label (the displayed text) and a slug (the path to the corresponding file in src/content/docs/). The Reference section can also be auto-generated with autogenerate: { directory: 'docs/reference' }.

Theme and Colors

Section titled “Theme and Colors”

Customize colors via CSS custom properties in your global stylesheet:

src/styles/global.css
:root {
  --sl-color-accent-low: #1a2e05;
  --sl-color-accent: #4c8f1a;
  --sl-color-accent-high: #b8e986;
}


:root[data-theme='dark'] {
  --sl-color-accent-low: #0d1f00;
  --sl-color-accent: #5ea82a;
  --sl-color-accent-high: #d4f5a8;
}

Style the accent colors for each theme (light and dark).

Section titled “Footer”

Add copyright information and links in the footer:

starlight({
  credits: true, // Shows "Built with Starlight"
  footer: {
    message: '© 2026 MyProject. All rights reserved.',
  },
});

Dark Mode

Section titled “Dark Mode”

By default, Lumen provides a theme selector (light, dark, auto). You can force a theme or disable the selector:

starlight({
  defaultTheme: 'dark', // 'light', 'dark', or 'auto'
});

Table of Contents

Section titled “Table of Contents”

Adjust the table of contents behavior displayed on the right side of each page:

starlight({
  tableOfContents: {
    minHeadingLevel: 2,
    maxHeadingLevel: 4,
  },
});

This configuration displays headings from h2 to h4 in the table of contents. By default, levels 2 and 3 are included.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.