Initial Starlight Plugins support

docs/astro.config.mjs

@@ -1,5 +1,6 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import starlightSearchDemo from '@astrojs/starlight-search-demo';
 
 export const locales = {
 	root: { label: 'English', lang: 'en' },
@@ -23,6 +24,8 @@ export default defineConfig({
 	integrations: [
 		starlight({
 			title: 'Starlight',
+			// TODO(HiDeoo) - Remove this once the search demo is no longer needed.
+			plugins: [starlightSearchDemo({ apiKey: '123456' })],
 			logo: {
 				light: '/src/assets/logo-light.svg',
 				dark: '/src/assets/logo-dark.svg',

docs/package.json

@@ -14,6 +14,7 @@
   },
   "dependencies": {
     "@astrojs/starlight": "workspace:*",
+    "@astrojs/starlight-search-demo": "workspace:*",
     "@types/culori": "^2.0.0",
     "astro": "^3.2.3",
     "culori": "^3.2.0",

docs/src/content/docs/reference/configuration.mdx

@@ -454,3 +454,20 @@ starlight({
 ```
 
 See the [Overrides Reference](/reference/overrides/) for details of all the components that you can override.
+
+### `plugins`
+
+**type:** [`StarlightPlugin[]`](/reference/plugins/#quick-api-reference)
+
+Extend Starlight with custom plugins.
+Starlight Plugins are an easy way to extend Starlight's functionality.
+
+Visit the [Starlight Plugins Showcase](/showcase/#community-plugins) to see a list of community plugins.
+
+```js
+starlight({
+	plugins: [starlightPlugin()],
+});
+```
+
+See the [Plugins Reference](/reference/plugins/) for details about creating your own plugins.

docs/src/content/docs/reference/plugins.md

@@ -0,0 +1,99 @@
+---
+title: Plugins Reference
+description: An overview of the Starlight plugin API.
+---
+
+Starlight Plugins provide an API to customize Starlight configuration, UI and behavior while also being easy to share and reuse.
+This page is for anyone interested in creating their own Starlight plugins.
+
+Lean more about using a Starlight plugin in the [Configuration Reference](/reference/configuration/#plugins) or visit the [Starlight Plugins Showcase](/showcase/#community-plugins) to see a list of community plugins.
+
+## Quick API Reference
+
+```ts
+interface StarlightPlugin {
+  name: string;
+  plugin: (options: {
+    config: StarlightUserConfig;
+    updateConfig: (newConfig: StarlightUserConfig) => void;
+    addIntegration: (integration: AstroIntegration) => void;
+    logger: AstroIntegrationLogger;
+  }) => void | Promise<void>;
+}
+```
+
+## Options
+
+### `config`
+
+**type:** `StarlightUserConfig`
+
+A read-only copy of the user-supplied [Starlight configuration](/reference/configuration).
+This configuration may have been updated by other plugins configured before the current one.
+
+### `updateConfig`
+
+**type:** `(newConfig: StarlightUserConfig) => void`
+
+A callback function to update the user-supplied [Starlight configuration](/reference/configuration).
+You only need to provide the configuration values that you want to update but no deep merge is performed.
+
+For example, to add a new [`social`](/reference/configuration/#social) media account to the configuration without overriding the existing ones:
+
+```ts {5-10}
+// plugin.ts
+export default {
+  name: 'add-twitter-plugin',
+  plugin({ config, updateConfig }) {
+    updateConfig({
+      social: {
+        ...config.social,
+        twitter: 'astrodotbuild',
+      },
+    });
+  },
+};
+```
+
+### `addIntegration`
+
+**type:** `(integration: AstroIntegration) => void`
+
+A callback function to add an [Astro integration](https://docs.astro.build/en/reference/integrations-reference/) required by the plugin.
+For example, to add the [React Astro integration](https://docs.astro.build/en/guides/integrations-guide/react/):
+
+```ts {7}
+// plugin.ts
+import react from '@astrojs/react';
+
+export default {
+  name: 'plugin-using-react',
+  plugin({ addIntegration }) {
+    addIntegration(react());
+  },
+};
+```
+
+### `logger`
+
+**type:** `AstroIntegrationLogger`
+
+An instance of the [Astro integration logger](https://docs.astro.build/en/reference/integrations-reference/#astrointegrationlogger) that you can use to write logs.
+Note that all logged messages will be prefixed with the plugin name.
+
+```ts {5}
+// plugin.ts
+export default {
+  name: 'long-process-plugin',
+  plugin({ logger }) {
+    logger.info('Starting long process…');
+    // Some long process…
+  },
+};
+```
+
+The example above will log a message that includes the provided info message:
+
+```shell
+[long-process-plugin] Starting long process…
+```

docs/src/content/docs/showcase.mdx

@@ -4,7 +4,7 @@ description: Discover sites built with Starlight and community tools that extend
 ---
 
 :::tip[Add your own!]
-Have you built a Starlight site or a tool for Starlight?
+Have you built a Starlight site, plugin, or a tool for Starlight?
 Open a PR adding a link to this page!
 :::
 
@@ -20,9 +20,15 @@ See all the [public project repos using Starlight on GitHub](https://github.com/
 
 ## Community plugins
 
+These community [plugins](/reference/configuration/#plugins) work alongside Starlight to extend its functionality.
+
+// TODO(HiDeoo) This new structure is a proposal and should only be used once we have at least a plugin to showcase.
+
+## Community tools and integrations
+
 import { CardGrid, LinkCard } from '@astrojs/starlight/components';
 
-These community tools, plugins, and integrations work alongside Starlight to extend its functionality.
+These community tools and integrations can be used to add features to your Starlight site.
 
 <CardGrid>
 	<LinkCard

packages/starlight-search-demo/index.ts

@@ -0,0 +1,68 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import type { AstroUserConfig, ViteUserConfig } from 'astro';
+
+/** The Starlight Search Demo plugin. */
+export default function starlightSearchDemo(opts: StarlightSearchDemoConfig): StarlightPlugin {
+	return {
+		name: 'starlight-search-demo',
+		plugin({ addIntegration, config, logger, updateConfig }) {
+			// If the user has already has a custom override for the Search component, don't override it.
+			if (config.components?.Search) {
+				if (!opts.ignoreComponentOverridesWarning) {
+					logger.warn(
+						`It looks like you already have a \`Search\` component override. To render \`@astrojs/starlight-search-demo\`, you can either:
+		- Remove the existing override for the \`Search\` component from your configuration
+		- Import and render \`@astrojs/starlight-search-demo/overrides/Search.astro\` in your custom override\n`
+					);
+				}
+			} else {
+				// Otherwise, add the Search component override to the user's configuration.
+				updateConfig({
+					components: {
+						...config.components,
+						Search: '@astrojs/starlight-search-demo/overrides/Search.astro',
+					},
+				});
+			}
+
+			// Add a custom Astro integration that will inject a Vite plugin to expose the Starlight
+			// Search Demo config via virtual modules.
+			addIntegration({
+				name: 'starlight-search-demo-integration',
+				hooks: {
+					'astro:config:setup': ({ updateConfig }) => {
+						updateConfig({
+							vite: {
+								plugins: [vitePluginStarlightSearchDemo(opts)],
+							},
+						} satisfies AstroUserConfig);
+					},
+				},
+			});
+		},
+	};
+}
+
+/** Vite plugin that exposes the Starlight Search Demo config via virtual modules. */
+function vitePluginStarlightSearchDemo(config: StarlightSearchDemoConfig): VitePlugin {
+	const moduleId = 'virtual:starlight-search-demo-config';
+	const resolvedModuleId = `\0${moduleId}`;
+	const moduleContent = `export default ${JSON.stringify(config)}`;
+
+	return {
+		name: 'vite-plugin-starlight-search-demo-config',
+		load(id) {
+			return id === resolvedModuleId ? moduleContent : undefined;
+		},
+		resolveId(id) {
+			return id === moduleId ? resolvedModuleId : undefined;
+		},
+	};
+}
+
+export interface StarlightSearchDemoConfig {
+	apiKey: string;
+	ignoreComponentOverridesWarning?: boolean;
+}
+
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];

packages/starlight-search-demo/overrides/Search.astro

@@ -0,0 +1,23 @@
+---
+import config from 'virtual:starlight-search-demo-config';
+---
+
+<input
+	autocapitalize="none"
+	enterkeyhint="search"
+	placeholder={`Search Demo with API Key '${config.apiKey}'`}
+	type="text"
+/>
+
+<style>
+	input {
+		background-color: crimson;
+		border: 2px solid darkred;
+		color: floralwhite;
+		width: 100%;
+	}
+
+	input::placeholder {
+		color: salmon;
+	}
+</style>

packages/starlight-search-demo/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@astrojs/starlight-search-demo",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Demo Starlight Plugin adding a 3rd party search engine to Starlight",
+  "author": "Chris Swithinbank <swithinbank@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/withastro/starlight",
+    "directory": "packages/starlight-search-demo"
+  },
+  "bugs": "https://github.com/withastro/starlight/issues",
+  "homepage": "https://starlight.astro.build",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./overrides/Search.astro": "./overrides/Search.astro"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.11.1"
+  }
+}

packages/starlight-search-demo/virtual.d.ts

@@ -0,0 +1,5 @@
+declare module 'virtual:starlight-search-demo-config' {
+	const StarlightSearchDemoConfig: import('./index').StarlightSearchDemoConfig;
+
+	export default StarlightSearchDemoConfig;
+}

packages/starlight/__tests__/plugins/config.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from 'vitest';
+import config from 'virtual:starlight/user-config';
+import { getSidebar } from '../../utils/navigation';
+import { runPlugins } from '../../utils/plugins';
+import { TestAstroIntegrationLogger } from '../test-config';
+
+test('reads and updates a configuration option', () => {
+	expect(config.title).toBe('Plugins - Custom');
+});
+
+test('overwrites a configuration option', () => {
+	expect(getSidebar('/', undefined)).toMatchObject([{ href: '/showcase/', label: 'Showcase' }]);
+});
+
+test('runs plugins in the order that they are configured and always passes down the latest user config', () => {
+	expect(config.description).toBe('plugin 1 - plugin 2 - plugin 3');
+});
+
+test('receives the user provided configuration without any Zod `transform`s applied', () => {
+	/**
+	 * If the `transform` associated to the favicon schema was applied, the favicon `href` would be
+	 * `invalid.svg`.
+	 * @see {@link file://./vitest.config.ts} for more details in the `test-plugin-1` plugin.
+	 */
+	expect(config.favicon.href).toBe('valid.svg');
+});
+
+test('does not expose plugins to the config virtual module', () => {
+	// @ts-expect-error - plugins are not serializable and thus not in the config virtual module.
+	expect(config.plugins).not.toBeDefined();
+});
+
+test('validates plugins configuration before running them', async () => {
+	expect(
+		async () =>
+			await runPlugins(
+				{
+					title: 'Test Docs',
+					// @ts-expect-error - invalid integration with no `plugin` callback.
+					plugins: [{ name: 'plugin-with-invalid-integration' }],
+				},
+				new TestAstroIntegrationLogger()
+			)
+	).rejects.toThrowError(/Invalid plugins config/);
+});

packages/starlight/__tests__/plugins/integration.test.ts

@@ -0,0 +1,45 @@
+import type { AstroIntegration } from 'astro';
+import { expect, test } from 'vitest';
+import { runPlugins } from '../../utils/plugins';
+import { TestAstroIntegrationLogger } from '../test-config';
+
+test('returns all integrations added by plugins without deduping them', async () => {
+	const integration1: AstroIntegration = {
+		name: 'test-integration-1',
+		hooks: {},
+	};
+
+	const integration2: AstroIntegration = {
+		name: 'test-integration-2',
+		hooks: {},
+	};
+
+	const { integrations } = await runPlugins(
+		{
+			title: 'Test Docs',
+			plugins: [
+				{
+					name: 'test-plugin-1',
+					plugin({ addIntegration, updateConfig }) {
+						updateConfig({ description: 'test' });
+						addIntegration(integration1);
+					},
+				},
+				{
+					name: 'test-plugin-1',
+					plugin({ addIntegration }) {
+						addIntegration(integration1);
+						addIntegration(integration2);
+					},
+				},
+			],
+		},
+		new TestAstroIntegrationLogger()
+	);
+
+	expect(integrations).toMatchObject([
+		{ name: 'test-integration-1' },
+		{ name: 'test-integration-1' },
+		{ name: 'test-integration-2' },
+	]);
+});