feat(search): upgrade DocSearch to v4

.changeset/chilly-seals-whisper.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight-docsearch': minor
+---
+
+Upgrades the [DocSearch dependency](https://github.com/algolia/docsearch) to stable v4  

docs/astro.config.mjs

@@ -2,6 +2,7 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import starlightLinksValidator from 'starlight-links-validator';
+import starlightDocSearch from '@astrojs/starlight-docsearch';
 import markdocGrammar from './grammars/markdoc.tmLanguage.json';
 
 export const locales = {
@@ -189,7 +190,14 @@ export default defineConfig({
 							errorOnInconsistentLocale: true,
 						}),
 					]
-				: [],
+				: [
+						starlightDocSearch({
+							appId: 'PMZUYBQDAK',
+							apiKey: '24b09689d5b4223813d9b8e48563c8f6',
+							indexName: '[Demo][Tmp] Astro Starlight',
+							askAi: 'askAIDemo'
+						}),
+				],
 		}),
 	],
 });

docs/package.json

@@ -18,6 +18,7 @@
   "dependencies": {
     "@astro-community/astro-embed-youtube": "^0.5.6",
     "@astrojs/starlight": "workspace:*",
+    "@astrojs/starlight-docsearch": "workspace:*",
     "@lunariajs/core": "^0.1.1",
     "@types/culori": "^2.1.1",
     "astro": "^5.6.1",

docs/src/content/docs/guides/site-search.mdx

@@ -199,36 +199,99 @@ Add translations of the modal UI for your language using Starlight’s built-in
 
    ```json title="src/content/i18n/en.json"
    {
-   	"docsearch.searchBox.resetButtonTitle": "Clear the query",
-   	"docsearch.searchBox.resetButtonAriaLabel": "Clear the query",
-   	"docsearch.searchBox.cancelButtonText": "Cancel",
-   	"docsearch.searchBox.cancelButtonAriaLabel": "Cancel",
+   	"docsearch.searchBox.clearButtonTitle": "Clear the query",
+   	"docsearch.searchBox.clearButtonAriaLabel": "Clear the query",
+   	"docsearch.searchBox.closeButtonText": "Close",
+   	"docsearch.searchBox.closeButtonAriaLabel": "Close",
+   	"docsearch.searchBox.placeholderText": "Search docs",
+   	"docsearch.searchBox.placeholderTextAskAi": "Ask AI: ",
+   	"docsearch.searchBox.placeholderTextAskAiStreaming": "Answering…",
    	"docsearch.searchBox.searchInputLabel": "Search",
+   	"docsearch.searchBox.backToKeywordSearchButtonText": "Back to keyword search",
+   	"docsearch.searchBox.backToKeywordSearchButtonAriaLabel": "Back to keyword search",
 
    	"docsearch.startScreen.recentSearchesTitle": "Recent",
    	"docsearch.startScreen.noRecentSearchesText": "No recent searches",
    	"docsearch.startScreen.saveRecentSearchButtonTitle": "Save this search",
    	"docsearch.startScreen.removeRecentSearchButtonTitle": "Remove this search from history",
    	"docsearch.startScreen.favoriteSearchesTitle": "Favorite",
    	"docsearch.startScreen.removeFavoriteSearchButtonTitle": "Remove this search from favorites",
+   	"docsearch.startScreen.recentConversationsTitle": "Recent conversations",
+   	"docsearch.startScreen.removeRecentConversationButtonTitle": "Remove this conversation from history",
 
    	"docsearch.errorScreen.titleText": "Unable to fetch results",
    	"docsearch.errorScreen.helpText": "You might want to check your network connection.",
 
    	"docsearch.footer.selectText": "to select",
+   	"docsearch.footer.submitQuestionText": "Submit question",
    	"docsearch.footer.selectKeyAriaLabel": "Enter key",
    	"docsearch.footer.navigateText": "to navigate",
    	"docsearch.footer.navigateUpKeyAriaLabel": "Arrow up",
    	"docsearch.footer.navigateDownKeyAriaLabel": "Arrow down",
    	"docsearch.footer.closeText": "to close",
+   	"docsearch.footer.backToSearchText": "Back to search",
    	"docsearch.footer.closeKeyAriaLabel": "Escape key",
-   	"docsearch.footer.searchByText": "Search by",
+   	"docsearch.footer.poweredByText": "Search by",
 
    	"docsearch.noResultsScreen.noResultsText": "No results for",
    	"docsearch.noResultsScreen.suggestedQueryText": "Try searching for",
    	"docsearch.noResultsScreen.reportMissingResultsText": "Believe this query should return results?",
-   	"docsearch.noResultsScreen.reportMissingResultsLinkText": "Let us know."
+   	"docsearch.noResultsScreen.reportMissingResultsLinkText": "Let us know.",
+
+   	"docsearch.resultsScreen.askAiPlaceholder": "Ask AI: ",
+
+   	"docsearch.askAiScreen.disclaimerText": "Answers are generated by AI and may be inaccurate.",
+   	"docsearch.askAiScreen.relatedSourcesText": "Related sources",
+   	"docsearch.askAiScreen.thinkingText": "Thinking…",
+   	"docsearch.askAiScreen.copyButtonText": "Copy",
+   	"docsearch.askAiScreen.copyButtonCopiedText": "Copied!",
+   	"docsearch.askAiScreen.copyButtonTitle": "Copy",
+   	"docsearch.askAiScreen.likeButtonTitle": "Like",
+   	"docsearch.askAiScreen.dislikeButtonTitle": "Dislike",
+   	"docsearch.askAiScreen.thanksForFeedbackText": "Thanks for your feedback!",
+   	"docsearch.askAiScreen.preToolCallText": "Searching…",
+   	"docsearch.askAiScreen.duringToolCallText": "Searching ",
+   	"docsearch.askAiScreen.afterToolCallText": "Searched",
+   	"docsearch.askAiScreen.aggregatedToolCallText": "Searched"
    }
    ```
 
 </Steps>
+
+#### Algolia Ask AI
+
+DocSearch v4 introduces an optional **Ask AI** conversational experience. To enable it, pass the `askAi` option to the Starlight DocSearch plugin — either as a plain string (your **assistant ID**) or as an object with overrides:
+
+```ts title="astro.config.mjs" ins={15-20}
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import starlightDocSearch from '@astrojs/starlight-docsearch';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      plugins: [
+        starlightDocSearch({
+          appId: 'YOUR_APP_ID',
+          apiKey: 'YOUR_SEARCH_API_KEY',
+          indexName: 'YOUR_INDEX_NAME',
+          // simplest form — just the assistant ID
+          // askAi: 'YOUR_ASSISTANT_ID',
+
+          // or full form with per-assistant overrides
+          askAi: {
+            assistantId: 'YOUR_ASSISTANT_ID',
+            // apiKey, appId & indexName default to the top-level values
+            // but can be overridden individually if needed
+            // apiKey: '...',
+            // appId: '...',
+            // indexName: '...',
+          },
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+If you want to stick with keyword search only, simply omit the `askAi` property.

packages/docsearch/DocSearch.astro

@@ -3,10 +3,9 @@ import '@docsearch/css/dist/modal.css';
 import type docsearch from '@docsearch/js';
 import './variables.css';
 
-type DocSearchTranslationProps = Pick<
-	Parameters<typeof docsearch>[0],
-	'placeholder' | 'translations'
->;
+type DocSearchProps = Parameters<typeof docsearch>[0];
+
+type DocSearchTranslationProps = Pick<DocSearchProps, 'placeholder' | 'translations'>;
 
 const pick = (keyStart: string) =>
 	Object.fromEntries(
@@ -26,8 +25,10 @@ const docsearchTranslations: DocSearchTranslationProps = {
 			searchBox: pick('docsearch.searchBox.'),
 			startScreen: pick('docsearch.startScreen.'),
 			errorScreen: pick('docsearch.errorScreen.'),
-			footer: pick('docsearch.footer.'),
+			askAiScreen: pick('docsearch.askAiScreen.'),
+			resultsScreen: pick('docsearch.resultsScreen.'),
 			noResultsScreen: pick('docsearch.noResultsScreen.'),
+			footer: pick('docsearch.footer.'),
 		},
 	},
 };
@@ -130,12 +131,60 @@ const docsearchTranslations: DocSearchTranslationProps = {
 			super();
 			window.addEventListener('DOMContentLoaded', async () => {
 				const { default: docsearch } = await import('@docsearch/js');
-				const options = { ...config, container: 'sl-doc-search' };
+				type DocSearchProps = Parameters<typeof docsearch>[0];
+
+				let translations;
 				try {
-					const translations = JSON.parse(this.dataset.translations || '{}');
-					Object.assign(options, translations);
+					translations = JSON.parse(this.dataset.translations || '{}');
 				} catch {}
-				docsearch(options);
+
+				// Extract the page language (e.g. <html lang="en">) and pass it to DocSearch
+				// as an Algolia facet filter so that the search results are scoped to the current
+				// language. If users already defined facet filters we preserve them while appending
+				// the new one.
+				let searchParameters: DocSearchProps['searchParameters'];
+
+				// Rebuild the askAi prop as an object:
+				// If the askAi prop is a string, treat it as the assistantId and use
+				// the default indexName, apiKey and appId from the main options.
+				// If the askAi prop is an object, spread its explicit values.
+				const askAiProp = config.askAi;
+				const isAskAiString = typeof askAiProp === 'string';
+
+				const askAi = askAiProp
+					? {
+							indexName: isAskAiString ? config.indexName : askAiProp.indexName,
+							apiKey: isAskAiString ? config.apiKey : askAiProp.apiKey,
+							appId: isAskAiString ? config.appId : askAiProp.appId,
+							assistantId: isAskAiString ? askAiProp : askAiProp.assistantId,
+							searchParameters: {},
+						}
+					: undefined;
+
+				const pageLang = document.documentElement.getAttribute('lang');
+				if (pageLang) {
+					searchParameters = config.searchParameters || {};
+					const existingFilters = searchParameters?.facetFilters ?? [];
+					// Ensure facetFilters is always an array of strings for simplicity.
+					searchParameters.facetFilters = Array.isArray(existingFilters)
+						? [...existingFilters, `lang:${pageLang}`]
+						: [existingFilters, `lang:${pageLang}`].filter(Boolean);
+
+					if (askAi) {
+						// Re-use the merged facetFilters from the search parameters so that
+						// Ask AI uses the same language filtering as the regular search.
+						askAi.searchParameters = { facetFilters: searchParameters.facetFilters };
+					}
+
+					const options = {
+						...config,
+						container: 'sl-doc-search',
+						translations,
+						searchParameters,
+						askAi,
+					};
+					docsearch(options as DocSearchProps);
+				}
 			});
 		}
 	}

packages/docsearch/README.md

@@ -2,6 +2,8 @@
 
 Algolia DocSearch plugin for the [Starlight][starlight] documentation theme for [Astro][astro].
 
+Supports DocSearch v4 with optional **Ask AI** conversational search.
+
 ## Documentation
 
 See the [Starlight site search guide][docs] for how to use this plugin.