Read and update the Starlight configuration 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 reading and updating the Starlight configuration in a Starlight plugin.

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.

Read the Starlight configuration

The config:setup Starlight plugin configuration setup function called when Starlight is initialized, is called with many options, including the Starlight configuration.

The config option is a read-only copy of the user-supplied Starlight configuration, which may have been updated by other plugins running before the current plugin.

The following example reads the title of the website from the user-supplied Starlight configuration and logs a message with it using the provided logger function:

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

export default function starlightPluginExample(): StarlightPlugin {
  return {
    name: 'starlight-plugin-example',
    hooks: {
      'config:setup'({ config, logger }) {
        // Read the title from the Starlight config and log it.
        logger.info(`The title of the site is "${config.title}".`)
      },
    },
  }
}

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

This function takes a partial Starlight configuration object containing the root-level properties you want to update as its first argument. Any provided values will override the existing ones in the user-supplied Starlight configuration.

The following example updates the description of the website in the user-supplied Starlight configuration:

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

export default function starlightPluginExample(): StarlightPlugin {
  return {
    name: 'starlight-plugin-example',
    hooks: {
      'config:setup'({ updateConfig }) {
        // Update the description in the Starlight config.
        updateConfig({ description: 'The updated description of the website.' })
      },
    },
  }
}

Extend a configuration value

To extend a root-level configuration value without overriding it, you can spread the existing value into the new one.

The following example extends the sidebar configuration by adding a new link at the end of the sidebar entries:

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 sidebar from the Starlight config or an empty array
        // if not provided.
        const currentSidebar = config.sidebar ?? []

        // Append a link to the existing sidebar entries.
        updateConfig({
          sidebar: [
            ...currentSidebar,
            { label: 'HiDeoo', link: 'https://hideoo.dev/' },
          ],
        })
      },
    },
  }
}

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