Use a remark or rehype plugin 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 using a remark or rehype plugin in a Starlight plugin, enabling you to extend the Markdown and HTML processing capabilities of Starlight.

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.

Use a remark or rehype plugin

Astro, which Starlight is built on top of, supports adding third-party remark and rehype plugins to the Markdown and HTML processing pipelines, respectively. Such plugins can be defined in the Astro configuration using the markdown.remarkPlugins and markdown.rehypePlugins options.

Starlight plugins can update these configuration options to add their own remark and rehype plugins.

The following example uses the addIntegration() function to add an Astro integration. The integration updates the user-supplied Astro configuration using the updateConfig() function to add the remark-emoji plugin.

import type { StarlightPlugin } from '@astrojs/starlight/types'
import remarkEmoji from 'remark-emoji'

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 }) {
              // Update the Astro config to include a new remark plugin.
              updateConfig({
                markdown: {
                  remarkPlugins: [remarkEmoji],
                },
              })
            },
          },
        })
      },
    },
  }
}

Use a custom remark or rehype plugin

If you want to use a custom remark or rehype plugin in a Starlight plugin, the same approach can be used.

The following example adds an Astro integration that updates the user-supplied Astro configuration to include a custom remark plugin defined in the Starlight plugin itself.

import type { StarlightPlugin } from '@astrojs/starlight/types'
import type { Plugin } from 'unified'
import type { Root } from 'mdast'

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 }) {
              // Update the Astro config to include a custom remark plugin.
              updateConfig({
                markdown: {
                  remarkPlugins: [remarkStarlightPluginExample],
                },
              })
            },
          },
        })
      },
    },
  }
}

const remarkStarlightPluginExample: Plugin<[], Root> = function () {
  return function (tree) {
    // Remark plugin logic goes here.
    // ...
  }
}

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