Skip to content
HiDeoo

How to create 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 creating a Starlight plugin using generator-starlight-plugin, a Yeoman generator to help create Starlight plugins and themes.

Create a Starlight plugin

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

  • 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 plugin:

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 plugin.

Terminal
Welcome to the Starlight plugin generator!


? Is your plugin a theme? (Use arrow keys)
  Yes
❯ No
? What is the name of your Starlight plugin? (starlight-plugin-name)
? What is the description of your Starlight plugin? (My awesome Starlight plugin)
? What single emoji represents your Starlight plugin? (used in the documentation) (🔋)
? 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 plugin.

Start the development

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

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

To start developing the Starlight plugin, edit the packages/plugin-name/index.ts file which will be the entry point of the plugin.

To test the plugin, 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.