Add DocSearch meta tags and search interceptor for improved search relevance (#952)

Co-authored-by: qodo-code-review[bot] <151058649+qodo-code-review[bot]@users.noreply.github.com>

Author: nortonandreev

docs/.vuepress/config.ts

@@ -14,6 +14,9 @@ import {linkCheckPlugin} from "./markdown/linkCheck";
 import {replaceLinkPlugin} from "./markdown/replaceLink";
 import {importCodePlugin} from "./markdown/xode/importCodePlugin";
 import {llmsPlugin} from '@vuepress/plugin-llms'
+import fs from 'fs';
+
+const searchInterceptor = fs.readFileSync(path.join(__dirname, 'util/searchInterceptor.js'), 'utf8');
 
 
 dotenv.config({path: path.join(__dirname, '..', '..', '.algolia', '.env')});
@@ -105,6 +108,8 @@ export default defineUserConfig({
             'data-user-analytics-cookie-enabled': false,
         }],
 
+        ["script", {}, searchInterceptor],
+
         // CSS override to hide the modal mask and wrapper entirely
         ['style', {}, `
           .redirect-modal-mask,

docs/.vuepress/configs/plugins/index.ts

@@ -7,16 +7,18 @@ import {hostname} from "./shared";
 import {redirect} from "./redirect";
 import type {SitemapPluginOptions} from "@vuepress/plugin-sitemap";
 
+const docsearch = {
+    apiKey: process.env.ALGOLIA_SEARCH_API_KEY,
+    indexName: process.env.ALGOLIA_INDEX_NAME,
+    appId: process.env.ALGOLIA_APPLICATION_ID,
+    maxResultsPerGroup: 10,
+}
+
 export default {
     components: {
         components: ["Badge", "VPBanner", "VPCard", "VidStack"]
     },
-    docsearch: {
-        apiKey: process.env.ALGOLIA_SEARCH_API_KEY,
-        indexName: process.env.ALGOLIA_INDEX_NAME,
-        appId: process.env.ALGOLIA_APPLICATION_ID,
-        maxResultsPerGroup:10 
-    },
+    docsearch,
     seo: seoPlugin,
     sitemap: {
         hostname: hostname,

docs/.vuepress/configs/plugins/seo.ts

@@ -2,6 +2,7 @@ import type { SeoPluginOptions } from "@vuepress/plugin-seo";
 import { match } from "ts-pattern";
 import type { App, HeadConfig, Page } from "vuepress";
 import { hostname } from "./shared";
+import { instance as versioning, type Version as VersionGroup } from "../../lib/versioning";
 
 interface DocumentationPath {
   version: string | null;
@@ -59,6 +60,100 @@ const normalize = (str: string): string =>
     .map(word => word.charAt(0).toUpperCase() + word.slice(1))
     .join(' ');
 
+/**
+ * Finds the version group for a given section path.
+ * @param section The section path (e.g., "server", "clients/dotnet", "server/kubernetes-operator").
+ * @returns The version group or null if not found.
+ */
+const findVersionGroup = (section: string): VersionGroup | null => {
+  // Special case for kubernetes-operator
+  if (section === "server/kubernetes-operator") {
+    return versioning.all.find((v) => v.id === "kubernetes-operator") || null;
+  }
+
+  // Try to find by basePath match
+  const byBasePath = versioning.all.find((v) => v.basePath === section);
+  if (byBasePath) {
+    return byBasePath;
+  }
+
+  // Try to match client sections to their version group IDs
+  const clientMatch = section.match(/^clients\/(\w+)/);
+  if (clientMatch) {
+    const clientName = clientMatch[1];
+    const clientId = `${clientName}-client`;
+    return versioning.all.find((v) => v.id === clientId) || null;
+  }
+
+  return null;
+};
+
+/**
+ * Gets the latest version string for a given section.
+ * @param section The section path.
+ * @returns The latest version string, or null if not found.
+ */
+const getLatestVersionForSection = (section: string): string | null => {
+  const versionGroup = findVersionGroup(section);
+  if (!versionGroup?.versions?.length) {
+    return null;
+  }
+
+  // Find the first non-preview, non-excluded version (which is the latest)
+  const excludedVersions = EXCLUDED_VERSIONS[section] || [];
+  const latestVersion = versionGroup.versions.find(
+    v => v.version && !v.preview && !excludedVersions.includes(v.version)
+  );
+
+  return latestVersion?.version || null;
+};
+
+/**
+ * Gets the docsearch:version content for a page.
+ * @param section The section path.
+ * @param currentVersion The current version string from the path.
+ * @returns The version content string (e.g., "v1.2,latest" or "v1.1" or "v1.0,legacy").
+ */
+const getDocSearchVersionContent = (section: string, currentVersion: string | null): string | null => {
+  if (!currentVersion) return null;
+
+  const parts: string[] = [currentVersion];
+  const latestVersion = getLatestVersionForSection(section);
+
+  if (latestVersion && currentVersion === latestVersion) parts.push("latest");
+
+  const isLegacy = ["legacy", "tcp"].some(seg => section.split("/").includes(seg));
+  if (isLegacy) parts.push("legacy");
+
+  return parts.join(",");
+};
+
+/**
+ * Maps a section path to a docsearch product name.
+ * @param section The section path (e.g., "clients/dotnet", "server").
+ * @returns The product name for docsearch (e.g., "dotnet_sdk", "js_sdk", "server") or null if not in the list.
+ */
+const getDocSearchProduct = (section: string): string | null => {
+  return match(section)
+    .with("clients/dotnet", () => "dotnet_sdk")
+    .with("clients/golang", () => "golang_sdk")
+    .with("clients/java", () => "java_sdk")
+    .with("clients/node", () => "js_sdk")
+    .with("clients/python", () => "python_sdk")
+    .with("clients/rust", () => "rust_sdk")
+    .with("clients/dotnet/legacy", () => "dotnet_sdk")
+    .with("clients/golang/legacy", () => "golang_sdk")
+    .with("clients/java/legacy", () => "java_sdk")
+    .with("clients/node/legacy", () => "js_sdk")
+    .with("clients/python/legacy", () => "python_sdk")
+    .with("clients/rust/legacy", () => "rust_sdk")
+    .with("clients/tcp/dotnet", () => "dotnet_sdk_tcp")
+    .with("cloud", () => "cloud")
+    .with("server/kubernetes-operator", () => "kubernetes_operator")
+    .with("server", () => "server")
+    .otherwise(() => null);
+};
+
 export const seoPlugin: SeoPluginOptions = {
   hostname,
 
@@ -96,6 +191,9 @@ export const seoPlugin: SeoPluginOptions = {
    * Sets the following tags:
    * e.g. <meta name="es:category" content=".NET Client" />
    *      <meta name="es:version" content="v1.0" />
+   *      <meta name="docsearch:version" content="v1.0,v1.1,v1.2" />
+   *      <meta name="docsearch:language" content="en" />
+   *      <meta name="docsearch:product" content="dotnet_sdk" />
    * 
    * If it's a legacy or tcp client, it will be labelled as "Legacy"
    */
@@ -131,5 +229,21 @@ export const seoPlugin: SeoPluginOptions = {
       .otherwise(() => normalize(section));
 
     head.push(["meta", { name: "es:category", content: category }]);
+
+    // Add DocSearch meta tags
+    // Add language tag (defaulting to "en")
+    head.push(["meta", { name: "docsearch:language", content: "en" }]);
+
+    // Add product tag (only if section is in the list)
+    const product = getDocSearchProduct(section);
+    if (product) {
+      head.push(["meta", { name: "docsearch:product", content: product }]);
+    }
+
+    // Add version tag with current version
+    const docSearchVersion = getDocSearchVersionContent(section, version);
+    if (docSearchVersion) {
+      head.push(["meta", { name: "docsearch:version", content: docSearchVersion }]);
+    }
   }
 };

docs/.vuepress/util/searchInterceptor.js

@@ -0,0 +1,70 @@
+function getFilters() {
+  // Read from meta tags to ensure we match what's in the HTML
+  // This includes "latest" when applicable, which is calculated server-side
+  const productMeta = document.querySelector('meta[name="docsearch:product"]');
+  const versionMeta = document.querySelector('meta[name="docsearch:version"]');
+  
+  const product = productMeta ? productMeta.getAttribute('content') : null;
+  const version = versionMeta ? versionMeta.getAttribute('content') : null;
+
+  return { 
+    product: product, 
+    version: version 
+  };
+}
+
+function buildOptionalFilters(product, version) {
+  const optionalFilters = [];
+  if (product) {
+    optionalFilters.push("product:" + product);
+  }
+  if (version) {
+    const versionParts = version.split(',');
+    versionParts.forEach((v) => {
+      optionalFilters.push("version:" + v.trim());
+    });
+  }
+  return optionalFilters;
+}
+
+function applyFiltersToBody(body, optionalFilters) {
+  if (optionalFilters.length > 0) {
+    body.requests = body.requests || [];
+    body.requests.forEach((req) => {
+      // Set optionalFilters directly on the request
+      req.optionalFilters = optionalFilters;
+    });
+  }
+}
+
+const searchInterceptor = function() {
+  // Intercept XMLHttpRequest (XHR)
+  const proxied = window.XMLHttpRequest.prototype.open;
+  window.XMLHttpRequest.prototype.open = function(method, url, async, username, password) {
+    const urlString = typeof url === 'string' ? url : url.toString();
+    if (urlString.includes('algolia.net')) {
+      const send = this.send;
+      this.send = function(data) {
+        if (typeof data === 'string' && data.trim()) {
+          try {
+            const body = JSON.parse(data);
+            const { product, version } = getFilters();
+            const optionalFilters = buildOptionalFilters(product, version);
+            
+            if (optionalFilters.length > 0) {
+              applyFiltersToBody(body, optionalFilters);
+              const modifiedData = JSON.stringify(body);
+              return send.apply(this, [modifiedData]);
+            }
+          } catch(e) {
+            console.error("Error modifying Algolia request");
+          }
+        }
+        return send.apply(this, [data]);
+      };
+    }
+    return proxied.call(this, method, url, async ?? true, username, password);
+  }
+}
+
+searchInterceptor();

package.json

@@ -36,7 +36,7 @@
     "@segment/analytics-next": "^1.79.0",
     "@vuepress/bundler-vite": "^2.0.0-rc.23",
     "@vuepress/helper": "^2.0.0-rc.110",
-    "@vuepress/plugin-docsearch": "^2.0.0-rc.110",
+    "@vuepress/plugin-docsearch": "2.0.0-rc.121",
     "@vuepress/plugin-notice": "^2.0.0-rc.110",
     "@vuepress/plugin-seo": "^2.0.0-rc.110",
     "@vuepress/plugin-sitemap": "^2.0.0-rc.110",