A plugin system for Starlight is something that has been discussed for a while on Discord. This issue is a proposal to discuss the potential design of such a system, explain why it could be useful, provide a few examples of what it could look like, and discuss / gather feedback on different APIs that could be exposed to plugins.

Feel free to comment on this issue to share your thoughts and ideas.

Motivation

Starlight is built on top of Astro which already supports Astro integrations to add new functionalities to a project using Astro (Starlight is actually an Astro integration).

Starlight plugins are not meant to replace Astro integrations but rather build on top of them to provide additional functionalities that are specific to Starlight. A common use case that has already been requested multiple times is to be able to read the Starlight configuration from another integration to customize its behavior based on it. This is something that is not possible at the moment and that could be achieved with a plugin system.

Usage

Plugins can be added to a Starlight configuration using a new plugins option. This option would accept an array of plugins just like Astro integrations do.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import myStarlightPlugin from 'my-starlight-plugin';

export default defineConfig({
  integrations: [
    await starlight({
      title: 'My Docs',
      plugins: [myStarlightPlugin()],
    }),
  ],
});

APIs

A Starlight plugin requires a name and a plugin function that will be called by Starlight with an object containing various helpers that can be used to interact with Starlight. This function can also optionally return an Astro integration that will be automatically used.

config & updateConfig()

A basic plugin that would require reading & updating the Starlight configuration could be similar to starlight-typedoc which generates some Markdown pages on disk, creates some sidebar navigation items for them and updates the Starlight sidebar configuration to display them.

function starlightTypeDocPlugin(options: StarlightTypeDocOptions) {
  const starlightTypeDoc: StarlightPlugin = {
    name: 'starlight-typedoc',
    async plugin({ config, updateConfig }) {
      // Generate the Markdown pages on disk.
      const pages = await generateTypeDocPages(options);
      // Create a new sidebar group for the generated pages.
      const sidebarGroup = getSidebarGroupFromPages(pages);
      // Add the new sidebar group to the Starlight configuration.
      updateConfig({
        sidebar: [...(config.sidebar ?? []), sidebarGroup],
      });
    },
  };

  return starlightTypeDoc;
}

function starlightBlogPlugin() {
  const starlightBlog: StarlightPlugin = {
    name: 'starlight-blog',
    plugin({ updateConfig }) {
      // Update the Starlight configuration to override various components and use the one provided
      // by the plugin.
      updateConfig({
        components: {
          SocialIcons: 'starlight-blog/components/SocialIcons.astro',
          Sidebar: 'starlight-blog/components/Sidebar.astro',
        },
      });

      // Return a classic Astro integration that will inject the blog routes.
      return {
        name: 'starlight-blog',
        hooks: {
          'astro:config:setup': ({ injectRoute }) => {
            injectRoute({
              entryPoint: 'starlight-blog/tags',
              pattern: '/blog/tags/[tag]',
            });
            injectRoute({
              entryPoint: 'starlight-blog/blog',
              pattern: '/blog/[...page]',
            });
          },
        },
      };
    },
  };

  return starlightBlog;
}

logger

I would love to be able to expose to plugins the AstroIntegrationLogger exposed to integrations in Astro v3:

function starlightExamplePlugin() {
  const starlightExample: StarlightPlugin = {
    name: 'starlight-example',
    plugin({ logger }) {
      logger.info('Computing some things…');
      // …
    },
  };

  return starlightExample;
}

• In various existing integrations/non-official plugins I created, I almost all the time end up re-installing kleur and creating a custom logger using Intl.DateTimeFormat to get a nice colored output matching the Astro one.
• We could get out of the box filtering when using the Astro programmatic API with a custom logLevel.

injectContent()

For plugins that adds dynamic data/pages like starlight-typedoc, having to output files on disk into src/content/docs/ that would either be committed or ignored by the user is not ideal.

Having an API that would allow to add pages to a Starlight website would be a great alternative. This API could be something like:

function starlightExamplePlugin() {
  const starlightExample: StarlightPlugin = {
    name: 'starlight-example',
    async plugin({ config }) {
      // Generate or fetch some markdown content based on the Starlight configuration.
      const markdown = await generateMarkdown(config);

      // Return a classic Astro integration that will add a page to the website.
      return {
        name: 'starlight-example',
        hooks: {
          'astro:config:setup': ({ injectContent }) => {
            injectContent('docs', () => [
              {
                id: 'injected.md',
                slug: 'injected',
                data: {
                  title: 'Injected page with generated markdown content',
                },
                content: markdown,
              },
            ]);
          },
        },
      };
    },
  };

  return starlightExample;
}

Note: technically, this would not require a plugin and should be available to any Astro integration but the example is here to show how it could be used in a plugin.

injectTranslations()

With component customization being worked on and some Discord discussions regarding potentially exposing a module using a more advanced version of the existing i18n t() helper (potentially using i18next), I feel like it would be nice to expose a injectTranslations() function to plugins that would allow them to add translations for custom keys (they would be scoped to the plugin name to avoid conflicts).

For example, internationalization support for starlight-blog is something that has already been requested, and instead of dealing with everything that would be required to support it, I think it could be nice to be able to do something like this:

function starlightBlogPlugin() {
  const starlightBlog: StarlightPlugin = {
    name: 'starlight-blog',
    plugin({ injectTranslations, updateConfig }) {
      // Update the Starlight configuration to override various components and use the one provided
      // by the plugin.
      updateConfig({
        // …
      });

      // Add some translations for this plugin.
      injectTranslations({
        en: {
          'sidebar.recentPosts': 'Recent posts',
        },
        fr: {
          'sidebar.recentPosts': 'Articles récents',
        },
      });

      // Return a classic Astro integration that will inject the blog routes.
      return {
        name: 'starlight-blog',
        // …
      };
    },
  };

  return starlightBlog;
}

and in my plugin custom component I could potentially do something like this:

---
import { useTranslations } from '@astrojs/starlight/i18n';

const t = useTranslations(Astro.props.locale);
---

<div>{t('starlight-blog.sidebar.recentPosts')}</div>

injectSettings()

For plugins accepting some configuration options that needs to be read in some Astro components, the go-to solution at the moment is to mimic what Starlight is currently doing for its configuration and expose the plugin configuration through a virtual module that can be imported in the components.

This works great and this what starlight-blog is currently doing for example but this adds some complexity, requires some boilerplate and feels like something that would be repeated a lot for all plugins doing something similar. Having a injectSettings() function that would allow to define some settings that would be injected automatically by Starlight in the existing settings virtual module could be a nice alternative (they would be scoped to the plugin name to avoid conflicts).

function starlightExamplePlugin(options: StarlightExampleOptions) {
  const starlightExample: StarlightPlugin = {
    name: 'starlight-example',
    plugin({ injectSettings }) {
      // Validate the plugin configuration and do some other things.
      // …

      // Expose the plugin configuration to the components.
      injectSettings(options);
    },
  };

  return starlightExample;
}

astro add

Plugins shipping an Astro integration should not use the astro-integration keyword to support automatic installation using astro add as this would install the plugin in the Astro configuration integrations array instead of the expected Starlight configuration plugins array.

At a later stage, if this is something that is wanted, we could potentially add a new starlight-plugin keyword to support this with astro add but this feels like something that is not needed at the moment and could be added later.

Implementation details

This section is mostly here to explain some implementation details so feel free to skip it if you are not interested.

export default function StarlightIntegration(opts: StarlightUserConfig): AstroIntegration[] {
  // Parse and validate the user configuration.
  const userConfig = StarlightConfigSchema.safeParse(opts);

  const Starlight: AstroIntegration = {
    name: '@astrojs/starlight',
    hooks: {
      'astro:config:setup': ({ config, injectRoute, updateConfig }) => {
        // Inject the Starlight routes.
        // …
        // Update the Astro configuration (remark/rehype plugins and exposes the Starlight
        // configuration through a virtual module).
        updateConfig({
          vite: {
            plugins: [vitePluginStarlightUserConfig(userConfig, config)],
          },
          // …
        });
      },
      // …
    },
  };

  // Returns a preset containing the Starlight integration and some other ones that uses the
  // Starlight configuration.
  return [starlightSitemap(userConfig), Starlight, mdx()];
}

export default async function StarlightIntegration({
  plugins,
  ...opts
}: StarlightUserConfig & StarlightPluginsUserConfig): Promise<AstroIntegration[]> {
  // Validate the plugins configurations
  const pluginsConfig = StarlightPluginsConfigSchema.safeParse({ plugins });

  let userProvidedConfig = opts;
  const pluginsIntegrations: AstroIntegration[] = [];

  // Loop through the plugins and run them.
  for (const { plugin } of parsedPluginsConfig.data.plugins) {
    // Run the plugin and accumulate the integrations it returns.
    const integrations = await plugin({
      config: userProvidedConfig,
      updateConfig: (configUpdates) => {
        // Update the user provided configuration with the updates from the plugin.
        // …
      },
    });

    if (integrations) {
      // Add the integrations returned by the plugin to the list of plugin integrations.
      // …
    }
  }

  // Parse and validate the user configuration updated by the plugins.
  const userConfig = StarlightConfigSchema.safeParse(userProvidedConfig);

  const Starlight: AstroIntegration = {
    // Same as before.
    // …
  };

  // Returns a preset containing the Starlight integration, some other ones that uses the Starlight
  // configuration and the plugins integrations.
  return [starlightSitemap(userConfig), Starlight, mdx(), ...pluginsIntegrations];
}

export default defineConfig({
  integrations: [
    // The `await` keyword would be required to support plugins.
    await starlight({
      title: 'My Docs',
      plugins: [myStarlightPlugin()],
    }),
  ],
});