Add Algolia DocSearch

.github/workflows/deploy-pages.yml

@@ -30,6 +30,10 @@ jobs:
 
       - name: Build
         run: npm run build
+        env:
+          ALGOLIA_APP_ID: ${{ vars.ALGOLIA_APP_ID }}
+          ALGOLIA_SEARCH_API_KEY: ${{ vars.ALGOLIA_SEARCH_API_KEY }}
+          ALGOLIA_INDEX_NAME: ${{ vars.ALGOLIA_INDEX_NAME }}
 
       - name: Deploy to Cloudflare Pages
         uses: cloudflare/wrangler-action@v3

README.md

@@ -17,6 +17,34 @@ npm run build
 
 Static output is written to `build/`.
 
+## Search
+
+The site uses [Algolia DocSearch](https://docsearch.algolia.com/). Search is
+enabled at build time when all three of these environment variables are set:
+
+- `ALGOLIA_APP_ID`
+- `ALGOLIA_SEARCH_API_KEY`
+- `ALGOLIA_INDEX_NAME`
+
+The API key must be Algolia's public, search-only key. Never use an Admin API
+key in the documentation site. Contextual search is enabled, so results are
+filtered to the language and documentation version currently being viewed.
+
+For local development, export the variables before starting the site:
+
+```bash
+export ALGOLIA_APP_ID="your-app-id"
+export ALGOLIA_SEARCH_API_KEY="your-search-only-api-key"
+export ALGOLIA_INDEX_NAME="your-index-name"
+npm start
+```
+
+For production, add the same names as GitHub repository **Actions variables**
+under **Settings → Secrets and variables → Actions → Variables**. These values
+are embedded in the public client bundle and are not secrets. If none are set,
+the site builds without search; if only some are set, the build fails with a
+configuration error.
+
 ## Deploy to Cloudflare Pages
 
 Production deploys use **Direct Upload** (not Cloudflare Git integration).

docusaurus.config.js

@@ -8,6 +8,39 @@ import {themes as prismThemes} from 'prism-react-renderer';
 
 // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
 
+const algoliaAppId = process.env.ALGOLIA_APP_ID;
+const algoliaSearchApiKey = process.env.ALGOLIA_SEARCH_API_KEY;
+const algoliaIndexName = process.env.ALGOLIA_INDEX_NAME;
+const algoliaValues = [algoliaAppId, algoliaSearchApiKey, algoliaIndexName];
+const configuredAlgoliaValues = algoliaValues.filter(Boolean).length;
+
+if (
+  configuredAlgoliaValues > 0 &&
+  configuredAlgoliaValues < algoliaValues.length
+) {
+  throw new Error(
+    'Algolia DocSearch requires ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY, and ALGOLIA_INDEX_NAME.',
+  );
+}
+
+const algolia =
+  configuredAlgoliaValues === algoliaValues.length
+    ? {
+        appId: algoliaAppId,
+        apiKey: algoliaSearchApiKey,
+        indexName: algoliaIndexName,
+        contextualSearch: true,
+        searchPagePath: 'search',
+      }
+    : undefined;
+
+const searchNavbarItem = algolia
+  ? /** @type {const} */ ({
+      type: 'search',
+      position: 'right',
+    })
+  : undefined;
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'nvm-windows Documentation',
@@ -97,6 +130,7 @@ const config = {
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
+      ...(algolia ? {algolia} : {}),
       // Replace with your project's social card
       image: 'img/docusaurus-social-card.jpg',
       colorMode: {
@@ -113,6 +147,7 @@ const config = {
             type: 'localeDropdown',
             position: 'right',
           },
+          ...(searchNavbarItem ? [searchNavbarItem] : []),
           {
             href: 'https://github.com/nvm-windows/docs',
             label: 'GitHub',