Add a pagefind boolean flag to user config (#1144)

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

.changeset/beige-shoes-whisper.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds a configuration option to disable site indexing with Pagefind and the default search UI

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

@@ -411,6 +411,16 @@ When `false`, the colors provided by the active syntax highlighting theme are us
 When using custom themes and setting this to `true`, you must provide at least one dark and one light theme to ensure proper color contrast.
 :::
 
+### `pagefind`
+
+**type:** `boolean`  
+**default:** `true`
+
+Define whether Starlight’s default site search provider [Pagefind](https://pagefind.app/) is enabled.
+
+Set to `false` to disable indexing your site with Pagefind.
+This will also hide the default search UI if in use.
+
 ### `head`
 
 **type:** [`HeadConfig[]`](#headconfig)

docs/src/content/docs/reference/overrides.md

@@ -234,6 +234,10 @@ The default implementation includes logic for rendering logos defined in Starlig
 Component used to render Starlight’s search UI.
 The default implementation includes the button in the header and the code for displaying a search modal when it is clicked and loading [Pagefind’s UI](https://pagefind.app/).
 
+When [`pagefind`](/reference/configuration/#pagefind) is disabled, the default search component will not be rendered.
+However, if you override `Search`, your custom component will always be rendered even if the `pagefind` configuration option is `false`.
+This allows you to add UI for alternative search providers when disabling Pagefind.
+
 #### `SocialIcons`
 
 **Default component:** [`SocialIcons.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/SocialIcons.astro)

packages/starlight/components/Header.astro

@@ -1,4 +1,5 @@
 ---
+import config from 'virtual:starlight/user-config';
 import type { Props } from '../props';
 
 import {
@@ -8,14 +9,20 @@ import {
 	SocialIcons,
 	ThemeSelect,
 } from 'virtual:starlight/components';
+
+/**
+ * Render the `Search` component if Pagefind is enabled or the default search component has been overridden.
+ */
+const shouldRenderSearch =
+	config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
 ---
 
 <div class="header sl-flex">
 	<div class="sl-flex">
 		<SiteTitle {...Astro.props} />
 	</div>
 	<div class="sl-flex">
-		<Search {...Astro.props} />
+		{shouldRenderSearch && <Search {...Astro.props} />}
 	</div>
 	<div class="sl-hidden md:sl-flex right-group">
 		<div class="sl-flex social-icons">

packages/starlight/index.ts

@@ -77,6 +77,7 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
 			},
 
 			'astro:build:done': ({ dir }) => {
+				if (!userConfig.pagefind) return;
 				const targetDir = fileURLToPath(dir);
 				const cwd = dirname(fileURLToPath(import.meta.url));
 				const relativeDir = relative(cwd, targetDir);

packages/starlight/utils/user-config.ts

@@ -190,6 +190,13 @@ const UserConfigSchema = z.object({
 	 */
 	expressiveCode: ExpressiveCodeSchema(),
 
+	/**
+	 * Define whether Starlight’s default site search provider Pagefind is enabled.
+	 * Set to `false` to disable indexing your site with Pagefind.
+	 * This will also hide the default search UI if in use.
+	 */
+	pagefind: z.boolean().default(true),
+
 	/** Specify paths to components that should override Starlight’s default components */
 	components: ComponentConfigSchema(),