Support passing more options to the DocSearch component (#2589)

Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>

6 files changed, 77 insertions, 9 deletions

diff --git a/.changeset/small-trainers-learn.md b/.changeset/small-trainers-learn.md
new file mode 100644
index 00000000..1ca10640
--- /dev/null
+++ b/.changeset/small-trainers-learn.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight-docsearch': minor
+---
+
+Adds support for some more of the DocSearch component’s configuration options
diff --git a/.github/labeler.yml b/.github/labeler.yml
index 4913a2e0..5b61ade1 100644
--- a/.github/labeler.yml
+++ b/.github/labeler.yml
@@ -26,6 +26,9 @@ i18n:
 '🌟 tailwind':
   - packages/tailwind/**
 
+'🌟 docsearch':
+  - packages/docsearch/**
+
 '🌟 markdoc':
   - packages/markdoc/**
 
diff --git a/docs/src/content/docs/guides/site-search.mdx b/docs/src/content/docs/guides/site-search.mdx
index 0de34add..083c245e 100644
--- a/docs/src/content/docs/guides/site-search.mdx
+++ b/docs/src/content/docs/guides/site-search.mdx
@@ -108,6 +108,15 @@ If you have access to [Algolia’s DocSearch program](https://docsearch.algolia.
 
 With this updated configuration, the search bar on your site will now open an Algolia modal instead of the default search modal.
 
+#### DocSearch configuration
+
+The Starlight DocSearch plugin also supports customizing the DocSearch component with the following additional options:
+
+- `maxResultsPerGroup`: Limit the number of results displayed for each search group. Default is `5`.
+- `disableUserPersonalization`: Prevent DocSearch from saving a user’s recent searches and favorites to local storage. Default is `false`.
+- `insights`: Enable the Algolia Insights plugin and send search events to your DocSearch index. Default is `false`.
+- `searchParameters`: An object customizing the [Algolia Search Parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/).
+
 #### Translating the DocSearch UI
 
 DocSearch only provides English UI strings by default.
diff --git a/packages/docsearch/DocSearch.astro b/packages/docsearch/DocSearch.astro
index 467192af..31ba7221 100644
--- a/packages/docsearch/DocSearch.astro
+++ b/packages/docsearch/DocSearch.astro
@@ -131,7 +131,8 @@ const docsearchTranslations: DocSearchTranslationProps = {
 			super();
 			window.addEventListener('DOMContentLoaded', async () => {
 				const { default: docsearch } = await import('@docsearch/js');
-				const options: Parameters<typeof docsearch>[0] = { ...config, container: 'sl-doc-search' };
+				type DocSearchOptions = Parameters<typeof docsearch>[0];
+				const options = { ...config, container: 'sl-doc-search' } as DocSearchOptions;
 				try {
 					const translations = JSON.parse(this.dataset.translations || '{}');
 					Object.assign(options, translations);
diff --git a/packages/docsearch/README.md b/packages/docsearch/README.md
new file mode 100644
index 00000000..8620a36c
--- /dev/null
+++ b/packages/docsearch/README.md
@@ -0,0 +1,18 @@
+# <img src="https://github.com/withastro/starlight/assets/357379/494fcd83-42aa-4891-87e0-87402fa0b6f3" alt="" align="left" width="40" height="40"> @astrojs/starlight-docsearch
+
+Algolia DocSearch plugin for the [Starlight][starlight] documentation theme for [Astro][astro].
+
+## Documentation
+
+See the [Starlight site search guide][docs] for how to use this plugin.
+
+## License
+
+MIT
+
+Copyright (c) 2023–present [Starlight contributors][contributors]
+
+[starlight]: https://starlight.astro.build/
+[astro]: https://astro.build/
+[docs]: https://starlight.astro.build/guides/site-search/#algolia-docsearch
+[contributors]: https://github.com/withastro/starlight/graphs/contributors
diff --git a/packages/docsearch/index.ts b/packages/docsearch/index.ts
index eee4e04e..3d7ff806 100644
--- a/packages/docsearch/index.ts
+++ b/packages/docsearch/index.ts
@@ -1,17 +1,49 @@
 import type { StarlightPlugin } from '@astrojs/starlight/types';
+import type docsearch from '@docsearch/js';
 import type { AstroUserConfig, ViteUserConfig } from 'astro';
 import { z } from 'astro/zod';
 
-/** Config options users must provide for DocSearch to work. */
-const DocSearchConfigSchema = z.object({
-	appId: z.string(),
-	apiKey: z.string(),
-	indexName: z.string(),
-});
-export type DocSearchConfig = z.input<typeof DocSearchConfigSchema>;
+type SearchOptions = Parameters<typeof docsearch>[0]['searchParameters'];
+
+/** DocSearch configuration options. */
+const DocSearchConfigSchema = z
+	.object({
+		// Required config without which DocSearch won’t work.
+		/** Your Algolia application ID. */
+		appId: z.string(),
+		/** Your Algolia Search API key. */
+		apiKey: z.string(),
+		/** Your Algolia index name. */
+		indexName: z.string(),
+		// Optional DocSearch component config (only the serializable properties can be included here)
+		/**
+		 * The maximum number of results to display per search group.
+		 * @default 5
+		 */
+		maxResultsPerGroup: z.number().optional(),
+		/**
+		 * Disable saving recent searches and favorites to the local storage.
+		 * @default false
+		 */
+		disableUserPersonalization: z.boolean().optional(),
+		/**
+		 * Whether to enable the Algolia Insights plugin and send search events to your DocSearch index.
+		 * @default false
+		 */
+		insights: z.boolean().optional(),
+		/**
+		 * The Algolia Search Parameters.
+		 * @see https://www.algolia.com/doc/api-reference/search-api-parameters/
+		 */
+		searchParameters: z.custom<SearchOptions>(),
+	})
+	.strict();
+
+type DocSearchUserConfig = z.input<typeof DocSearchConfigSchema>;
+export type DocSearchConfig = z.output<typeof DocSearchConfigSchema>;
 
 /** Starlight DocSearch plugin. */
-export default function starlightDocSearch(userConfig: DocSearchConfig): StarlightPlugin {
+export default function starlightDocSearch(userConfig: DocSearchUserConfig): StarlightPlugin {
 	const opts = DocSearchConfigSchema.parse(userConfig);
 	return {
 		name: 'starlight-docsearch',