Skip to content
HiDeoo

How to create a Starlight theme

-

Starlight plugins offer an easy-to-share and reusable way to customize the look and feel of Starlight, the fully-featured documentation theme built on top of the Astro framework. A Starlight plugin provides all the necessary tools to create a Starlight theme, from adding custom CSS to overriding Starlight components.

This guide will walk you through the process of creating a Starlight theme using generator-starlight-plugin, a Yeoman generator to help create Starlight plugins and themes.

Create a Starlight theme

The generator-starlight-plugin Yeoman generator is an opinionated but still lightweight Yeoman generator to help create Starlight plugins and themes:

  • Opinionated: Git and pnpm are required to generate a monorepo containing a Starlight plugin package and a Starlight documentation project acting at the same time as a playground to test the plugin. The plugin is expected to be written in TypeScript, hosted on GitHub, and licensed under the MIT license.
  • Lightweight: Formatting, linting, testing, bundling, publishing, and deploying the documentation, which are all optional for a Starlight plugin, are not enforced by the generator. You are free to add them to the project as you see fit using the tools and services you prefer.

To run the generator, run the following command in the terminal from the directory where you want to work on the theme:

Terminal
npx -p yo -p @hideoo/generator-starlight-plugin -- yo @hideoo/starlight-plugin

A series of prompts will guide you through the process of creating a Starlight theme.

Terminal
Welcome to the Starlight plugin generator!


? Is your plugin a theme? (Use arrow keys)
❯ Yes
  No
? What is the name of your Starlight theme? (starlight-theme-name)
? What is the description of your Starlight theme? (My awesome Starlight theme)
? What single emoji represents your Starlight plugin? (used in the documentation) (🎨)
? What is the name of your theme CSS cascade layer? (my-theme)
? What is your GitHub username? (ghost)

After answering the prompts, the generator will scaffold a new monorepo containing a Starlight plugin package and a Starlight documentation project acting as a playground to test the theme.

Start the development

The generated project uses a monorepo structure with different pnpm workspaces:

  • docs/: A Starlight documentation project to document the theme that also acts as a playground.
  • packages/theme-name/: A package containing the Starlight plugin and theme.

To start developing the Starlight theme, edit the packages/theme-name/styles.css file which will be the theme CSS file automatically added to Starlight by the plugin.

To test the theme, run the following command from the docs/ directory:

Terminal
pnpm dev

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