Customizing the Theme

The theme is opinionated so most packs need zero customization. When you do need to adjust something, prefer the seams the theme leaves open — a customCss file and Starlight’s own config — over editing the package. That keeps you on the upgrade path.

Point the logo somewhere else

By default the header logo links back to your site’s base. To send it to a shared portal instead, set logoHref:

astro.config.mjs

starlight({
  plugins: [
    nebari({ logoHref: 'https://packs.nebari.dev/' }),
  ],
});

Override design tokens

The theme’s stylesheets load before any customCss you register, so your CSS always wins. Override Starlight’s semantic variables rather than the raw Nebari tokens.

1. Create a stylesheet for your overrides:

   src/styles/overrides.css

   :root {
     --sl-color-accent: oklch(0.6 0.2 300);
     --sl-color-accent-high: oklch(0.9 0.05 300);
   }
   
   :root[data-theme='light'] {
     --sl-color-accent: oklch(0.55 0.2 300);
   }

2. Register it after the plugin:

   astro.config.mjs

   starlight({
     title: 'My Pack',
     plugins: [nebari()],
     customCss: ['./src/styles/overrides.css'],
   });

3. Restart the dev server so Astro picks up the new stylesheet.

Caution

Set light and dark values separately. The theme defines tokens under both :root[data-theme='light'] and :root[data-theme='dark']; an override on plain :root alone can lose the CSS cascade in light mode.

Add your own components overrides Advanced

Starlight lets you swap individual layout components. The theme already overrides SiteTitle, Head, Footer, and ThemeSelect. You can override others freely, but if you override one the theme also sets, list yours after the plugin so it wins:

astro.config.mjs

starlight({
  plugins: [nebari()],
  components: {
    // Fine — theme doesn't touch this one:
    Hero: './src/components/MyHero.astro',
  },
});

Danger

Overriding SiteTitle, Head, Footer, or ThemeSelect replaces the theme’s versions of them — you lose the branded logo, self-hosted fonts, footer, or the Nebari theme toggle respectively. Only do this if you’re deliberately replacing that piece.

Where files go

A customized pack typically grows a styles/ and maybe a components/ directory:

• Directorysrc

  • Directorycontent/docs/

    • …
  • Directorystyles

    • overrides.css your token overrides
  • Directorycomponents

    • MyHero.astro optional component overrides
• astro.config.mjs

Verify your changes

Customizations to color and contrast are easy to get subtly wrong. Before you ship:

Visual

Toggle light and dark with the control in the header and check every accent, link, and callout in both modes.

Automated

Run the accessibility checks so contrast regressions fail loudly:

bunx playwright test

See the Configuration Options reference for the complete list of what the plugin sets and what it leaves to you.