Static Site Generators in Production

Customizing Starlight Without Forking the Theme

Starlight is easy to brand badly. The fastest route to "make it look like our product" is to copy its layout components into your project and edit them, and that route turns every Starlight release into a manual merge. The alternative takes the same afternoon and costs nothing on upgrade: change design tokens first, override named components second, wrap rather than replace, and package repeated changes as a plugin.

This guide applies that ladder to a real brand restyle — the one from Docusaurus vs Starlight for Product Documentation — and measures what each rung cost at upgrade time. It sits under Docs Frameworks: Docusaurus, Starlight and VitePress.

Prerequisites

  • A Starlight project (Astro 5, Starlight 0.30 or newer).
  • The brand's colour palette with light and dark values, the web font files, and a logo in SVG.
  • A preview deploy for every pull request so each change is reviewed on a real URL — see Preview Environments for Pull Requests.

Rung 1: Design Tokens in CSS

Starlight reads roughly sixty CSS custom properties. Colours, the accent hue, fonts, the content width and the sidebar width are all tokens, and most brand requirements end here.

/* src/styles/brand.css */
:root {
  --sl-font: 'Inter Variable', system-ui, sans-serif;
  --sl-font-mono: 'JetBrains Mono', ui-monospace, monospace;
  --sl-content-width: 48rem;
  --sl-sidebar-width: 17rem;
}
:root[data-theme='light'] {
  --sl-color-accent-low: #e6ddf3;
  --sl-color-accent: #6a4c93;
  --sl-color-accent-high: #34244d;
  --sl-color-white: #1f2937;
  --sl-color-gray-1: #334155;
}
:root[data-theme='dark'] {
  --sl-color-accent-low: #2a1f3b;
  --sl-color-accent: #b79de0;
  --sl-color-accent-high: #ece4f8;
}

Register the file with customCss: ['./src/styles/brand.css'] and add the fonts with @fontsource-variable/inter imported from the same list, so they are bundled and preloaded rather than fetched from a third party — the reasoning is in Self-Hosting Google Fonts to Eliminate Layout Shift.

Check contrast in both themes before moving on. The accent colour is used for link text and the active sidebar item, and a brand purple that passes on white often fails on Starlight's dark background; that is why the dark block above uses a lighter tint rather than the same hex.

Four rungs of Starlight customisation and what each touches Four stacked layers. Tokens change CSS variables and touch no markup. Overrides replace a named component with one of the same props. Wrappers import the original and add content around it. Plugins bundle config, overrides and routes for reuse. Upgrade risk rises from none to low as you go up. Stop at the lowest rung that meets the design 1 · Tokens --sl-color-accent, --sl-font, widths no upgrade risk 2 · Override components: { Header: './Header.astro' } props contract 3 · Wrap import Default from '@astrojs/starlight/components/…' low 4 · Plugin config hooks + overrides + routes, versioned package low, shared
Copying Starlight's source is deliberately absent from this ladder: nothing in a normal brand restyle requires it.

Rung 2: Override a Named Component

When the markup itself must change — a product switcher in the header, a support link in the footer — override that one component. Starlight exposes components such as Header, Footer, PageTitle, Sidebar, SocialIcons, ThemeSelect and Head by name.

// astro.config.mjs
starlight({
  title: 'Acme Docs',
  components: {
    SocialIcons: './src/components/ProductSwitcher.astro',
    Footer: './src/components/Footer.astro',
  },
});

An override receives Astro.locals.starlightRoute with the same data the original uses — the current page's entry, the sidebar, the locale, the edit URL — so it can render anything the original could. Keep overrides small and presentational; anything that fetches data or computes navigation belongs in a plugin or a content collection, where it can be tested independently.

Rung 3: Wrap the Original

Most "override" requests are really "add something next to the existing thing". Import the default component and render it inside yours:

---
// src/components/Footer.astro
import Default from '@astrojs/starlight/components/Footer.astro';
const { entry } = Astro.locals.starlightRoute;
const owner = entry.data.owner ?? 'docs-team';
---
<Default><slot /></Default>
<p class="page-owner">Maintained by <a href={`/team/${owner}/`}>{owner}</a></p>

Because the original still renders, upstream improvements to the footer (a new "last updated" format, an accessibility fix) arrive automatically. Custom front matter such as owner is added by extending the docs schema with docsSchema({ extend: z.object({ owner: z.string().optional() }) }) in src/content.config.ts, so a typo in front matter fails the build instead of rendering silently.

Replace versus wrap on upgrade Two lanes. In the replace lane, the site renders a copied footer, so an upstream fix in the new Starlight release never reaches the site. In the wrap lane, the site renders the original footer plus an addition, so the upstream fix flows through automatically on upgrade. An upstream accessibility fix ships in Starlight x.y+1 Replace upstream Footer (fixed) your copied Footer fix never arrives Wrap upstream Footer (fixed) <Default /> + owner line fix flows through Wrapping keeps you on the upstream code path; copying freezes you on the version you copied
The same logic applies to Docusaurus: swizzle with --wrap rather than --eject whenever the change is additive.

Rung 4: Package Shared Changes as a Plugin

When two or more docs sites share a brand — a product docs site and a developer portal, say — the overrides and CSS belong in a Starlight plugin published as an internal package:

// packages/starlight-acme/index.js
export default function acmeTheme() {
  return {
    name: 'starlight-acme',
    hooks: {
      'config:setup'({ config, updateConfig }) {
        updateConfig({
          customCss: [...(config.customCss ?? []), 'starlight-acme/brand.css'],
          components: {
            Footer: 'starlight-acme/Footer.astro',
            ...config.components,   // a site can still override locally
          },
        });
      },
    },
  };
}

Each site then lists plugins: [acmeTheme()] and gets the brand with one dependency. The spread of config.components last lets an individual site override a component the plugin also sets, which avoids forking the plugin for one site's exception.

Measured Impact

The restyle used all four rungs: 41 lines of token CSS, two overrides, one wrapper and, later, a plugin shared with a second site. Twelve months of upgrades were logged:

UpgradeFiles changed in our codeTime to upgrade
0.28 → 0.29010 min
0.29 → 0.30 (props rename)1 override45 min
0.30 → 0.3108 min
0.31 → 0.32012 min
0.32 → 0.3309 min
0.33 → 0.34011 min
Upgrade minutes over twelve months, two strategies Bars for six upgrades. The token-and-wrap site took 10, 45, 8, 12, 9 and 11 minutes, 95 in total. A comparison site that had copied eight layout components took 90, 240, 60, 120, 75 and 150 minutes, 735 in total. Minutes per upgrade: tokens and wrappers vs copied components 0.29 0.30 0.31 0.32 0.33 0.34 240 min 45 tokens + wrap: 95 min total 8 copied components: 735 min total Time-tracked upgrades on two production docs sites over the same twelve months
Roughly an eightfold difference in upgrade effort, almost all of it in merging changes into copied markup.

The comparison site, a sibling team's docs that had copied eight layout components into its repository, spent 735 minutes on the same six upgrades and skipped two releases entirely because the merge was too large to schedule. Skipped upgrades compound: the eventual jump covered three releases of breaking changes at once.

Testing Customisations Before Each Upgrade

Low upgrade cost is not the same as zero risk. A props rename in an overridden component fails loudly at build time, which is fine; a visual regression in a wrapped component builds cleanly and ships. Three cheap checks catch nearly everything.

Pin, then bump deliberately. Pin @astrojs/starlight to an exact version in package.json and let a dependency bot open one pull request per release. Each pull request gets a preview deploy, so the upgrade is reviewed on a real URL before anyone merges it.

Screenshot the four templates. Capture the homepage, a long guide, a page with tabs and asides, and the 404 page in both themes, and diff them against the production build. On this site that is eight screenshots and about forty seconds in CI using the approach from Visual Regression Testing on Preview Deploys. The 0.30 props rename showed up there first, as a footer missing its "last updated" line.

Run the accessibility pass on overrides only. An override can silently drop an aria-label that the original carried. Running axe-core against the pages that render your overridden components — not the whole site — keeps the check under ten seconds and focused on the code you own.

Read the changelog for your override list. Keep the list of overridden component names in a comment at the top of astro.config.mjs. When a release note mentions one of those names, that is the pull request to review carefully; the rest can be merged on a green preview.

Together these turned upgrades into a routine the on-call writer could merge, rather than a task that waited for an engineer with Astro experience.

Pitfalls & Rollback

  • Styling by selector instead of token. CSS such as .sidebar-content a { color: purple } depends on class names that are not a public API. Use the documented custom properties; they are stable across releases.
  • Overriding Head to add one tag. Use the head config option for extra meta, link or script tags instead of replacing the whole component.
  • Forgetting dark mode. Token blocks need a [data-theme='dark'] variant; otherwise the brand accent drops below AA contrast on dark backgrounds.
  • Plugins that swallow local overrides. Spread the site's own config.components after the plugin's so a site can still override locally.
  • Rollback: every rung is additive configuration. Removing a line from components, deleting the customCss entry or removing the plugin restores Starlight's default for that piece without touching content.

Conclusion

Branding Starlight is a configuration exercise when approached in order: tokens for colour, type and width; named overrides for structural changes; wrappers for additions; a plugin once more than one site shares the result. The site that followed that order upgraded six times in a year for 95 minutes of total effort. The site that copied components spent nearly eight times as long and fell behind. Choose the lowest rung that meets the design, and treat any urge to copy Starlight's source as a sign that the change belongs one rung down.

FAQ

Can I change Starlight's colours without overriding components?

Yes. Starlight's theme is driven by CSS custom properties such as --sl-color-accent and --sl-font. Set them in a stylesheet listed under customCss, separately for light and dark mode, and every component picks them up.

What happens to my component overrides when Starlight upgrades?

Overrides receive the same props as the built-in component, so they keep working unless a release changes those props. Breaking prop changes are listed in the changelog. In a year of upgrades on one site, one of six overrides needed a change.

Can an override reuse the original component?

Yes. Import the default from @astrojs/starlight/components and render it inside your own component. This wrapping pattern lets you add content around the original without copying its markup.

Should I use a Starlight plugin or a component override?

Use an override for one site's layout change. Use a plugin when several sites need the same change or when you need to modify configuration, add routes or register several overrides together.