polish contextual search

packages/docusaurus-theme-classic/src/theme/hooks/useSearchFilters.ts → packages/docusaurus-theme-classic/src/theme/hooks/useContextualSearchFilters.ts

@@ -8,14 +8,14 @@ import {useAllDocsData, useActivePluginAndVersion} from '@theme/hooks/useDocs';
 import {useDocsPreferredVersionByPluginId} from '../../utils/docsPreferredVersion/useDocsPreferredVersion';
 import {DEFAULT_SEARCH_TAG, docVersionSearchTag} from '../../utils/searchUtils';
 
-type SearchFilters = {
+type ContextualSearchFilters = {
   language: string;
   tags: string[];
 };
 
 // We may want to support multiple search engines, don't couple that to Algolia/DocSearch
 // Maybe users will want to use its own search engine solution
-export default function useSearchFilters(): SearchFilters {
+export default function useContextualSearchFilters(): ContextualSearchFilters {
   const allDocsData = useAllDocsData();
   const activePluginAndVersion = useActivePluginAndVersion();
   const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();

packages/docusaurus-theme-classic/src/utils/searchUtils.ts

@@ -8,5 +8,5 @@
 export const DEFAULT_SEARCH_TAG = 'default';
 
 export function docVersionSearchTag(pluginId: string, versionName: string) {
-  return `${pluginId}-${versionName}`;
+  return `docs-${pluginId}-${versionName}`;
 }

packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.js

@@ -14,7 +14,7 @@ import Link from '@docusaurus/Link';
 import Head from '@docusaurus/Head';
 import useSearchQuery from '@theme/hooks/useSearchQuery';
 import {DocSearchButton, useDocSearchKeyboardEvents} from '@docsearch/react';
-import {useAlgoliaSearchParameters} from '../../utils/algoliaSearchUtils';
+import {useAlgoliaContextualSearchParameters} from '../../utils/algoliaSearchUtils';
 
 let DocSearchModal = null;
 
@@ -32,16 +32,18 @@ function ResultsFooter({state, onClose}) {
   );
 }
 
-function DocSearch(props) {
+function DocSearch({contextualSearch, ...props}) {
   const {siteMetadata} = useDocusaurusContext();
 
+  const contextualSearchParameters = useAlgoliaContextualSearchParameters();
+
   // we let user override default searchParameters if he wants to
   const searchParameters = {
-    ...useAlgoliaSearchParameters(),
+    ...(contextualSearch ? contextualSearchParameters : {}),
     ...props.searchParameters,
   };
 
-  console.log('searchParameters', searchParameters);
+  console.log('searchParameters', contextualSearch, searchParameters);
 
   const {withBaseUrl} = useBaseUrlUtils();
   const history = useHistory();

packages/docusaurus-theme-search-algolia/src/utils/algoliaSearchUtils.js

@@ -5,11 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import useSearchFilters from '@theme/hooks/useSearchFilters';
+import useContextualSearchFilters from '@theme/hooks/useContextualSearchFilters';
 
 // Translate search-engine agnostic seach filters to Algolia search filters
-export function useAlgoliaSearchParameters() {
-  const {language, tags} = useSearchFilters();
+export function useAlgoliaContextualSearchParameters() {
+  const {language, tags} = useContextualSearchFilters();
 
   const languageFilter = `language:${language}`;
 

packages/docusaurus-theme-search-algolia/src/validateThemeConfig.js

@@ -16,9 +16,14 @@ exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
 
 const Schema = Joi.object({
   algolia: Joi.object({
+    // Docusaurus attributes
+    contextualSearch: Joi.boolean().default(false),
+
+    // Algolia attributes
     appId: Joi.string().default(DEFAULT_CONFIG.appId),
     apiKey: Joi.string().required(),
     indexName: Joi.string().required(),
+    searchParameters: Joi.object().default({}).unknown(),
   })
     .label('themeConfig.algolia')
     .required()
@@ -30,5 +35,17 @@ exports.validateThemeConfig = function validateThemeConfig({
   validate,
   themeConfig,
 }) {
-  return validate(Schema, themeConfig);
+  const normalizedThemeConfig = validate(Schema, themeConfig);
+
+  if (
+    normalizedThemeConfig &&
+    normalizedThemeConfig.algolia.contextualSearch &&
+    normalizedThemeConfig.algolia.searchParameters &&
+    normalizedThemeConfig.algolia.searchParameters.facetFilters
+  ) {
+    throw new Error(
+      'If you are using algolia.contextualSearch: true, you should not provide algolia.searchParameters.facetFilters, as it is computed for you dynamically',
+    );
+  }
+  return normalizedThemeConfig;
 };

website/docs/search.md

@@ -27,7 +27,14 @@ module.exports = {
     algolia: {
       apiKey: 'YOUR_API_KEY',
       indexName: 'YOUR_INDEX_NAME',
-      searchParameters: {}, // Optional (if provided by Algolia)
+
+      // Optional: see doc section bellow
+      contextualSearch: true,
+
+      // Optional: Algolia search parameters
+      searchParameters: {},
+
+      //... other Algolia params
     },
     // highlight-end
   },
@@ -40,6 +47,37 @@ The `searchParameters` option used to be named `algoliaOptions` in Docusaurus v1
 
 :::
 
+### Contextual search
+
+Contextual search is mostly useful for versioned Docusaurus sites.
+
+Let's consider you have 2 docs versions, v1 and v2. When you are browsing v2 docs, it would be odd to return search results for the v1 documentation. Sometimes v1 and v2 docs are quite similar, and you would end up with duplicate search results for the same query (one result per version).
+
+To solve this problem, the contextual search feature understands that you are browsing a specific docs version, and will create the search query filters dynamically.
+
+- browsing `/docs/v1/myDoc`, search results will only include **v1** docs (+ other unversioned pages)
+- browsing `/docs/v2/myDoc`, search results will only include **v2** docs (+ other unversioned pages)
+
+```jsx title="docusaurus.config.js"
+module.exports = {
+  // ...
+  themeConfig: {
+    // ...
+    // highlight-start
+    algolia: {
+      contextualSearch: true,
+    },
+    // highlight-end
+  },
+};
+```
+
+:::caution
+
+If you decide to use contextual search, you can't provide `algolia.searchParameters.facetFilters`, as we compute this `facetFilters` attribute for you dynamically.
+
+:::
+
 ### Styling your Algolia search
 
 By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.

website/docusaurus.config.js

@@ -247,12 +247,12 @@ module.exports = {
       trackingID: 'UA-141789564-1',
     },
     algolia: {
-      // apiKey: '47ecd3b21be71c5822571b9f59e52544',
-
-      appId: 'P64CMYBJ4G',
-      apiKey: 'fef25a54d94b17b4c6e659bc732edd52',
-
+      apiKey: '47ecd3b21be71c5822571b9f59e52544',
       indexName: 'docusaurus-2',
+      // contextualSearch: true,
+      searchParameters: {
+        facetFilters: [`version:current`],
+      },
     },
     navbar: {
       hideOnScroll: true,