Support multisite search on pagefind (#2858)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

3 files changed, 121 insertions, 35 deletions

diff --git a/.changeset/dry-geese-pretend.md b/.changeset/dry-geese-pretend.md
new file mode 100644
index 00000000..e860c8cc
--- /dev/null
+++ b/.changeset/dry-geese-pretend.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Adds support for Pagefind’s multisite search features
diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
index 28132f34..53c04e0b 100644
--- a/docs/src/content/docs/reference/configuration.mdx
+++ b/docs/src/content/docs/reference/configuration.mdx
@@ -457,8 +457,10 @@ This will also hide the default search UI if in use.
 
 Pagefind cannot be enabled when the [`prerender`](#prerender) option is set to `false`.
 
-Set `pagefind` to an object to configure the Pagefind search client.
-See [“Customize Pagefind's result ranking”](https://pagefind.app/docs/ranking/) in the Pagefind documentation for more details about using the `pagefind.ranking` option to control how search result ranking is calculated.
+Set `pagefind` to an object to configure the Pagefind search client:
+
+- See [“Customize Pagefind's result ranking”](https://pagefind.app/docs/ranking/) in the Pagefind documentation for more details about using the `pagefind.ranking` option to control how search result ranking is calculated
+- See [“Searching multiple sites”](https://pagefind.app/docs/multisite/) in the Pagefind documentation for more details about using the `pagefind.mergeIndex` option to control how to search accros multiple sites
 
 #### `PagefindOptions`
 
@@ -470,6 +472,21 @@ interface PagefindOptions {
 		termSaturation?: number;
 		termSimilarity?: number;
 	};
+	indexWeight?: number;
+	mergeIndex?: Array<{
+		bundlePath: string;
+		indexWeight?: number;
+		basePath?: string;
+		baseUrl?: string;
+		mergeFilter?: Record<string, string | string[]>;
+		language?: string;
+		ranking?: {
+			pageLength?: number;
+			termFrequency?: number;
+			termSaturation?: number;
+			termSimilarity?: number;
+		};
+	}>;
 }
 ```
 
diff --git a/packages/starlight/schemas/pagefind.ts b/packages/starlight/schemas/pagefind.ts
index 7889f330..e5de22f9 100644
--- a/packages/starlight/schemas/pagefind.ts
+++ b/packages/starlight/schemas/pagefind.ts
@@ -1,43 +1,107 @@
 import { z } from 'astro/zod';
 
+const indexWeightSchema = z.number().nonnegative().optional();
+const pagefindRankingWeightsSchema = z.object({
+	/**
+	 * Set Pagefind’s `pageLength` ranking option.
+	 *
+	 * The default value is `0.1` and values must be in the range `0` to `1`.
+	 *
+	 * @see https://pagefind.app/docs/ranking/#configuring-page-length
+	 */
+	pageLength: z.number().min(0).max(1).default(0.1),
+	/**
+	 * Set Pagefind’s `termFrequency` ranking option.
+	 *
+	 * The default value is `0.1` and values must be in the range `0` to `1`.
+	 *
+	 * @see https://pagefind.app/docs/ranking/#configuring-term-frequency
+	 */
+	termFrequency: z.number().min(0).max(1).default(0.1),
+	/**
+	 * Set Pagefind’s `termSaturation` ranking option.
+	 *
+	 * The default value is `2` and values must be in the range `0` to `2`.
+	 *
+	 * @see https://pagefind.app/docs/ranking/#configuring-term-saturation
+	 */
+	termSaturation: z.number().min(0).max(2).default(2),
+	/**
+	 * Set Pagefind’s `termSimilarity` ranking option.
+	 *
+	 * The default value is `9` and values must be greater than or equal to `0`.
+	 *
+	 * @see https://pagefind.app/docs/ranking/#configuring-term-similarity
+	 */
+	termSimilarity: z.number().min(0).default(9),
+});
+const pagefindIndexOptionsSchema = z.object({
+	/**
+	 * Overrides the URL path that Pagefind uses to load its search bundle
+	 */
+	basePath: z.string().optional(),
+	/**
+	 * Appends the given baseURL to all search results. May be a path, or a full domain
+	 */
+	baseUrl: z.string().optional(),
+	/**
+	 * Multiply all rankings for this index by the given weight.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#changing-the-weighting-of-individual-indexes
+	 */
+	indexWeight: indexWeightSchema,
+	/**
+	 * Apply this filter configuration to all search results from this index.
+	 *
+	 * Only applies in multisite setups.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#filtering-results-by-index
+	 */
+	mergeFilter: z.record(z.string(), z.string().or(z.array(z.string()).nonempty())).optional(),
+	/**
+	 * Language of this index.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#merging-a-specific-language-index
+	 */
+	language: z.string().optional(),
+	/**
+	 * Configure how search result rankings are calculated by Pagefind.
+	 */
+	ranking: pagefindRankingWeightsSchema.optional(),
+});
+
 const pagefindSchema = z.object({
+	/**
+	 * Configure how search results from the current website are weighted by Pagefind
+	 * compared to results from other sites when using the `mergeIndex` option.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#changing-the-weighting-of-individual-indexes
+	 */
+	indexWeight: indexWeightSchema,
 	/** Configure how search result rankings are calculated by Pagefind. */
-	ranking: z
-		.object({
-			/**
-			 * Set Pagefind’s `pageLength` ranking option.
-			 *
-			 * The default value is `0.1` and values must be in the range `0` to `1`.
-			 *
-			 * @see https://pagefind.app/docs/ranking/#configuring-page-length
-			 */
-			pageLength: z.number().min(0).max(1).default(0.1),
-			/**
-			 * Set Pagefind’s `termFrequency` ranking option.
-			 *
-			 * The default value is `0.1` and values must be in the range `0` to `1`.
-			 *
-			 * @see https://pagefind.app/docs/ranking/#configuring-term-frequency
-			 */
-			termFrequency: z.number().min(0).max(1).default(0.1),
-			/**
-			 * Set Pagefind’s `termSaturation` ranking option.
-			 *
-			 * The default value is `2` and values must be in the range `0` to `2`.
-			 *
-			 * @see https://pagefind.app/docs/ranking/#configuring-term-saturation
-			 */
-			termSaturation: z.number().min(0).max(2).default(2),
+	ranking: pagefindRankingWeightsSchema.default({}),
+	/**
+	 * Configure how search indexes from different sites are merged by Pagefind.
+	 *
+	 * @see https://pagefind.app/docs/multisite/#searching-additional-sites-from-pagefind-ui
+	 */
+	mergeIndex: z
+		.array(
 			/**
-			 * Set Pagefind’s `termSimilarity` ranking option.
-			 *
-			 * The default value is `9` and values must be greater than or equal to `0`.
+			 * Each entry of this array represents a `PagefindIndexOptions` from pagefind.
 			 *
-			 * @see https://pagefind.app/docs/ranking/#configuring-term-similarity
+			 * @see https://github.com/CloudCannon/pagefind/blob/v1.3.0/pagefind_web_js/lib/coupled_search.ts#L549
 			 */
-			termSimilarity: z.number().min(0).default(9),
-		})
-		.default({}),
+			pagefindIndexOptionsSchema.extend({
+				/**
+				 * Set Pagefind’s `bundlePath` mergeIndex option.
+				 *
+				 * @see https://pagefind.app/docs/multisite/#searching-additional-sites-from-pagefind-ui
+				 */
+				bundlePath: z.string(),
+			})
+		)
+		.optional(),
 });
 
 export const PagefindConfigSchema = () => pagefindSchema;