Read and update the Astro 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 Astro 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 Astro configuration

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

The astroConfig option is a read-only copy of the user-supplied Astro configuration.

The following example reads the deployment URL of the website from the user-supplied Astro 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'({ astroConfig, logger }) {
        // Read the deployment URL from the Astro config and log it.
        logger.info(`Deployment URL: ${astroConfig.site}`)
      },
    },
  }
}

Update the Astro configuration

To update the user-supplied Astro configuration in a Starlight plugin, you can use the addIntegration() function provided in the config:setup Starlight plugin configuration setup function to add an Astro integration.

Using a similar API to Starlight plugins, Astro integrations can update the user-supplied Astro configuration using an updateConfig() function provided in the astro:config:setup Astro integration configuration setup function.

This function takes a partial Astro configuration object containing the properties you want to update as its first argument. Any provided values will be merged with the user-supplied Astro configuration and any other integration Astro configuration updates.

The following example disables the SmartyPants formatter in the user-supplied Astro configuration:

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

export default function starlightPluginExample(): StarlightPlugin {
  return {
    name: 'starlight-plugin-example',
    hooks: {
      'config:setup'({ addIntegration }) {
        // Add an Astro integration to update the Astro config.
        addIntegration({
          name: 'starlight-plugin-example-integration',
          hooks: {
            'astro:config:setup'({ updateConfig }) {
              // Disable the SmartyPants formatter in the Astro config.
              updateConfig({ markdown: { smartypants: false } })
            },
          },
        })
      },
    },
  }
}

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