CSS & Styling

You can style your Starlight site with custom CSS files or use the Starlight Tailwind plugin.

For a quick way to change the default style of your site, check out community themes.

Custom CSS styles

Customize the styles applied to your Starlight site by providing additional CSS files to modify or extend Starlight’s default styles.

1. Add a CSS file to your src/ directory. For example, you could set a wider default column width and larger text size for page titles:

   src/styles/custom.css

   :root {
     --sl-content-width: 50rem;
     --sl-text-5xl: 3.5rem;
   }

2. Add the path to your CSS file to Starlight’s customCss array in astro.config.mjs:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'Docs With Custom CSS',
         customCss: [
           // Relative path to your custom CSS file
           './src/styles/custom.css',
         ],
       }),
     ],
   });

You can see all the CSS custom properties used by Starlight that you can set to customize your site in the props.css file on GitHub.

Cascade layers

Starlight uses cascade layers internally to manage the order of its styles. This ensures a predictable CSS order and allows for simpler overrides. Any custom unlayered CSS will override the default styles from the starlight layer.

If you are using cascade layers, you can use @layer in your custom CSS to define the order of precedence for different layers relative to Starlight’s styles:

src/styles/custom.css

@layer my-reset, starlight, my-overrides;

The example above defines a custom layer named my-reset, applied before all Starlight layers, and another named my-overrides, applied after all Starlight layers. Any styles in the my-overrides layer would take precedence over Starlight’s styles, but Starlight could still change styles set in the my-reset layer.

Tailwind CSS

Tailwind CSS support in Astro projects is provided by the Tailwind Vite plugin. Starlight provides complementary CSS to help configure Tailwind for compatibility with Starlight’s styles.

The Starlight Tailwind CSS applies the following configuration:

• Configures Tailwind’s dark: variants to work with Starlight’s dark mode.
• Uses Tailwind theme colors and fonts in Starlight’s UI.
• Restores essential parts of Tailwind’s Preflight reset styles.

Create a new project with Tailwind

Start a new Starlight project with Tailwind CSS pre-configured using create astro:

npm

npm create astro@latest -- --template starlight/tailwind

pnpm

pnpm create astro --template starlight/tailwind

Yarn

yarn create astro --template starlight/tailwind

Add Tailwind to an existing project

If you already have a Starlight site and want to add Tailwind CSS, follow these steps.

1. Set up Tailwind in your project by running the following command and following the instructions in your terminal:

   npm

   npx astro add tailwind

   pnpm

   pnpm astro add tailwind

   Yarn

   yarn astro add tailwind

2. Install Starlight’s Tailwind compatibility package:

   npm

   npm install @astrojs/starlight-tailwind

   pnpm

   pnpm add @astrojs/starlight-tailwind

   Yarn

   yarn add @astrojs/starlight-tailwind

3. Replace the contents of the src/styles/global.css file scaffolded by Astro for compatibility with Starlight:

   src/styles/global.css

   @layer base, starlight, theme, components, utilities;
   
   @import '@astrojs/starlight-tailwind';
   @import 'tailwindcss/theme.css' layer(theme);
   @import 'tailwindcss/utilities.css' layer(utilities);

4. Update the Starlight config to use the Tailwind CSS file:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   import tailwindcss from '@tailwindcss/vite';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'Docs with Tailwind',
         customCss: [
           // Path to your Tailwind base styles:
           './src/styles/global.css',
         ],
       }),
     ],
     vite: { plugins: [tailwindcss()] },
   });

Styling Starlight with Tailwind

Starlight will use values from your Tailwind theme config in its UI.

If set, the following CSS custom properties will override Starlight’s default styles:

• --color-accent-* — used for links and current item highlighting
• --color-gray-* — used for background colors and borders
• --font-sans — used for UI and content text
• --font-mono — used for code examples

src/styles/global.css

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

@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

@theme {
  /* Your preferred text font. Starlight uses a system font stack by default. */
  --font-sans: 'Atkinson Hyperlegible';
  /* Your preferred code font. Starlight uses system monospace fonts by default. */
  --font-mono: 'IBM Plex Mono';
  /* Your preferred accent color. Indigo is closest to Starlight’s defaults. */
  --color-accent-50: var(--color-indigo-50);
  --color-accent-100: var(--color-indigo-100);
  --color-accent-200: var(--color-indigo-200);
  --color-accent-300: var(--color-indigo-300);
  --color-accent-400: var(--color-indigo-400);
  --color-accent-500: var(--color-indigo-500);
  --color-accent-600: var(--color-indigo-600);
  --color-accent-700: var(--color-indigo-700);
  --color-accent-800: var(--color-indigo-800);
  --color-accent-900: var(--color-indigo-900);
  --color-accent-950: var(--color-indigo-950);
  /* Your preferred gray scale. Zinc is closest to Starlight’s defaults. */
  --color-gray-50: var(--color-zinc-50);
  --color-gray-100: var(--color-zinc-100);
  --color-gray-200: var(--color-zinc-200);
  --color-gray-300: var(--color-zinc-300);
  --color-gray-400: var(--color-zinc-400);
  --color-gray-500: var(--color-zinc-500);
  --color-gray-600: var(--color-zinc-600);
  --color-gray-700: var(--color-zinc-700);
  --color-gray-800: var(--color-zinc-800);
  --color-gray-900: var(--color-zinc-900);
  --color-gray-950: var(--color-zinc-950);
}

Theming

Starlight’s color theme can be controlled by overriding its default custom properties. These variables are used throughout the UI with a range of gray shades used for text and background colors and an accent color used for links and to highlight current items in navigation.

Color theme editor

Use the sliders below to modify Starlight’s accent and gray color palettes. The dark and light preview areas will show the resulting colors, and the whole page will also update to preview your changes.

Use the Contrast Level option to specify which of the Web Content Accessibility Guideline colour contrast standards to meet.

When you’re happy with your changes, copy the CSS or Tailwind code below and use it in your project.

Presets Ocean Forest Oxide Nebula Default Random

Contrast Level

AA AAA

Accent

Pick color

Hue 269 Chroma 0.27

Gray

Pick color

Hue 270 Chroma 0.016

Dark mode

Body text is displayed in a gray shade with a high contrast with the background. Links are colored. Some text, like the table of contents, has a lower contrast. Inline code has a distinct background.

Light mode

Body text is displayed in a gray shade with a high contrast with the background. Links are colored. Some text, like the table of contents, has a lower contrast. Inline code has a distinct background.

CSS

Add the following CSS to your project in a custom CSS file to apply this theme to your site.

Tailwind

Add the following CSS variables to the @theme block in your Tailwind CSS file to apply this theme to your site.