Add custom CSS in a Starlight plugin

Starlight plugins offer an easy-to-share and reusable way to customize and extend Starlight, the fully-featured documentation theme built on top of the Astro framework.

This guide will walk you through the process of adding custom CSS in a Starlight plugin, enabling you to customize the styles applied to a Starlight project.

Prerequisites

You will need to have a Starlight plugin set up. If you don’t have one yet, you can follow the “How to create a Starlight plugin” note to create one or refer to the Starlight documentation for a complete reference.

Add custom CSS

Starlight provides a customCss configuration option to add additional CSS files to a Starlight website by referencing their paths. Starlight plugins can read and update this configuration option to add their own custom CSS files in order to customize the styles applied to a Starlight project.

This option supports local CSS files relative to the root of the project, e.g. './src/custom.css' which is an approach that would not work in a Starlight plugin, as the CSS files would be part of the plugin package and not the Starlight project. To support this use case, Starlight plugins can export a CSS file from the plugin package, and reference the associated identifier in the customCss option.

Export a CSS file

To export a CSS file from a Starlight plugin, you can add a new entry in the exports field of the plugin’s package.json file.

The following example adds a new entry point name ./styles that points to a styles.css file in the plugin’s root directory:

{
  "name": "starlight-plugin-example",
  "version": "0.0.1",
  "license": "MIT",
  "type": "module",
  "exports": {
    ".": "./plugin.ts"
    ".": "./plugin.ts",
    "./styles": "./styles.css"
  },
  "peerDependencies": {
    "@astrojs/starlight": ">=0.34"
  }
}

Add the CSS file to the Starlight configuration

To reference the previously exported CSS file in the Starlight configuration, the starlight-plugin-example/styles identifier can be used in the customCss option of the Starlight configuration.

To update the user-supplied Starlight configuration in a Starlight plugin, you can use the updateConfig() function provided in the config:setup Starlight plugin configuration setup function.

The following example updates the customCss option in the user-supplied Starlight configuration to prepend the plugin’s custom CSS file:

import type { StarlightPlugin } from '@astrojs/starlight/types'

export default function starlightPluginExample(): StarlightPlugin {
  return {
    name: 'starlight-plugin-example',
    hooks: {
      'config:setup'({ config, updateConfig }) {
        // Get the user-supplied custom CSS files from the Starlight config or an empty
        // array if not provided.
        const currentCustomCss = config.customCss ?? []

        // Prepend a plugin-specific CSS file to the custom CSS files.
        updateConfig({
          customCss: ['starlight-plugin-example/styles', ...currentCustomCss],
        })
      },
    },
  }
}

After creating the styles.css file in the plugin’s root directory, you can add custom CSS styles to it.

To learn more about Starlight plugins, check out the “Starlight Plugins by Example” notebook for additional guides and examples.