Customising

A token

Every colour, face, radius and measure is a CSS variable. Set one in a sheet in Starlight’s customCss, and it wins over the theme’s:

astro.config.mjs

starlight({ customCss: ["./src/styles/custom.css"] });

src/styles/custom.css

:root {
  --hypha-font-serif: "Fraunces", serif;
  --hypha-radius-panel: 4px;
}

A colour set on :root holds in both schemes. Set it under :root[data-theme="light"] or "dark" for one. The list is under Tokens.

A component

The theme replaces some of Starlight’s components with its own. Replace any of them with yours in Starlight’s components, and yours wins:

astro.config.mjs

starlight({
  components: { Footer: "./src/components/Footer.astro" },
  plugins: [starlightThemeHypha()],
});

The theme’s words

The theme says a few things of its own: “Close the menu”, “Read more”, the keys under search. Translate them as you translate Starlight’s, in a file per language in src/content/i18n/:

src/content/i18n/fr.json

{
  "hypha.menu.close": "Fermer le menu",
  "hypha.nav.sections": "Sections",
  "hypha.nav.site": "Site",
  "hypha.siteTitle.home": "{{title}}, accueil",
  "hypha.feature.readMore": "En savoir plus",
  "hypha.notFound.title": "Rien n’est écrit ici.",
  "hypha.notFound.home": "Retour au début",
  "hypha.search.choose": "pour choisir",
  "hypha.search.open": "pour ouvrir",
  "hypha.search.close": "pour fermer",
  "hypha.search.failed": "La recherche n’a pas pu se charger. Vérifiez votre connexion, puis tapez à nouveau.",
  "hypha.github.label": "{{repo}} sur GitHub",
  "hypha.github.version": "version {{version}}",
  "hypha.github.stars_one": "{{count}} étoile",
  "hypha.github.stars_other": "{{count}} étoiles",
  "hypha.github.forks_one": "{{count}} fork",
  "hypha.github.forks_other": "{{count}} forks"
}

The file needs Starlight’s i18n collection. A word you leave out is said in English.

Beside your own styles

The theme’s utilities are prefixed hypha: and its variables --hypha-, so they share no name with your Tailwind build or design system. Its styles are in the hypha cascade layer, after Starlight’s and before yours, so your styles win over the theme’s without !important.

If you declare your own layer order, as Starlight’s guide to Tailwind does, put hypha after starlight:

src/styles/global.css

@layer base, starlight, hypha, theme, components, utilities;

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/utilities.css" layer(utilities);

This site does exactly that: the palette picker on Colours is styled in its own Tailwind, on the theme’s tokens.

A demo of your own

The theme styles a page’s text: its headings, lists, tables and links. Anything inside an element with the class not-content is left alone, so a demo of your own components keeps its own look:

<div class="not-content">
  <MyCard title="Unstyled by the theme" />
</div>