Anatomy of 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.

What is a Starlight plugin?

A Starlight plugin in its simplest form is a JavaScript object with a name and a hooks property. Plugins are referenced in the Starlight configuration in the plugins option, which is an array of plugin objects.

The name property of a plugin is a string that uniquely identifies the plugin, while the hooks property is an object that contains functions that Starlight calls to run plugin code at specific times.

The following example shows a minimal Starlight plugin that logs a message when the plugin is loaded:

import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        {
          name: 'starlight-plugin-example',
          hooks: {
            'config:setup'({ logger }) {
              // Log a message when the plugin is loaded.
              logger.info('Starlight Plugin Example has been loaded.')
            },
          },
        },
      ],
      title: 'My Docs',
    }),
  ],
})

Plugin hooks

Multiple hooks are available in Starlight plugins, enabling you to define the plugin’s behavior, inject custom translation strings, and more. Check out the Starlight plugin reference for a complete list of available hooks.

config:setup

The mandatory config:setup plugin configuration setup function is called when Starlight is initialized. This hook is called with many useful parameters to define the plugin’s behavior, from reading and updating the Starlight configuration to overriding Starlight’s default components.

i18n:setup

The optional i18n:setup plugin internationalization setup function can be used to inject custom translation strings, enabling you to provide localized text for the plugin’s features.

Create a Starlight plugin

As showcased in the previous sections, writing a Starlight plugin is as simple as creating a JavaScript object in the Starlight configuration. Even though this is a great way to get started with Starlight plugins, you will most likely want to create a dedicated package for the plugin, enabling you to share it with others and reuse it in multiple Starlight projects.

Check out the “How to create a Starlight plugin” note for more information on how to create and set up a Starlight plugin package.

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