feat(docusaurus-adapter): support docsearch key and adapter docs

adapters/docusaurus-theme-search-algolia/.gitignore

@@ -0,0 +1 @@
+lib

adapters/docusaurus-theme-search-algolia/.npmignore

@@ -0,0 +1,3 @@
+.tsbuildinfo*
+tsconfig*
+__tests__

adapters/docusaurus-theme-search-algolia/README.md

@@ -0,0 +1,27 @@
+# `@docsearch/docusaurus-adapter`
+
+Algolia search component for Docusaurus.
+
+## Usage
+
+Prefer configuring the adapter with `themeConfig.docsearch`:
+
+```js
+// docusaurus.config.js
+export default {
+  // ...
+  themeConfig: {
+    docsearch: {
+      appId: 'APP_ID',
+      apiKey: 'SEARCH_API_KEY',
+      indexName: 'INDEX_NAME',
+      askAi: {
+        assistantId: 'ASSISTANT_ID',
+        sidePanel: true,
+      },
+    },
+  },
+};
+```
+
+`themeConfig.algolia` is still supported as a backward-compatible alias.

adapters/docusaurus-theme-search-algolia/libtmp/docSearchVersion.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export declare const docSearchVersionString = "4.5.4";

adapters/docusaurus-theme-search-algolia/libtmp/docSearchVersion.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docSearchVersionString = void 0;
+const react_1 = require("@docsearch/react");
+exports.docSearchVersionString = react_1.version;

adapters/docusaurus-theme-search-algolia/libtmp/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. And its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { LoadContext, Plugin } from '@docusaurus/types';
+export default function themeSearchAlgolia(context: LoadContext): Plugin<void>;
+export { validateThemeConfig } from './validateThemeConfig';

adapters/docusaurus-theme-search-algolia/libtmp/index.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. And its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateThemeConfig = void 0;
+exports.default = themeSearchAlgolia;
+const theme_translations_1 = require("@docusaurus/theme-translations");
+const opensearch_1 = require("./opensearch");
+const utils_1 = require("./utils");
+function themeSearchAlgolia(context) {
+    const { baseUrl, siteConfig: { themeConfig }, i18n: { currentLocale }, } = context;
+    const { algolia: { searchPagePath }, } = themeConfig;
+    return {
+        name: 'docsearch-docusaurus-algolia-search',
+        getThemePath() {
+            return '../lib/theme';
+        },
+        getTypeScriptThemePath() {
+            return '../src/theme';
+        },
+        getDefaultCodeTranslationMessages() {
+            return (0, theme_translations_1.readDefaultCodeTranslationMessages)({
+                locale: currentLocale,
+                name: 'theme-search-algolia',
+            });
+        },
+        contentLoaded({ actions: { addRoute } }) {
+            if (searchPagePath) {
+                addRoute({
+                    path: (0, utils_1.normalizeUrl)([baseUrl, searchPagePath]),
+                    component: '@theme/SearchPage',
+                    exact: true,
+                });
+            }
+        },
+        async postBuild() {
+            if ((0, opensearch_1.shouldCreateOpenSearchFile)({ context })) {
+                await (0, opensearch_1.createOpenSearchFile)({ context });
+            }
+        },
+        injectHtmlTags() {
+            if ((0, opensearch_1.shouldCreateOpenSearchFile)({ context })) {
+                return { headTags: (0, opensearch_1.createOpenSearchHeadTags)({ context }) };
+            }
+            return {};
+        },
+    };
+}
+var validateThemeConfig_1 = require("./validateThemeConfig");
+Object.defineProperty(exports, "validateThemeConfig", { enumerable: true, get: function () { return validateThemeConfig_1.validateThemeConfig; } });

adapters/docusaurus-theme-search-algolia/libtmp/opensearch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) Facebook, Inc. And its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { HtmlTags, LoadContext } from '@docusaurus/types';
+export declare function shouldCreateOpenSearchFile({ context }: {
+    context: LoadContext;
+}): boolean;
+export declare function createOpenSearchFile({ context }: {
+    context: LoadContext;
+}): Promise<void>;
+export declare function createOpenSearchHeadTags({ context }: {
+    context: LoadContext;
+}): HtmlTags;

adapters/docusaurus-theme-search-algolia/libtmp/opensearch.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. And its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldCreateOpenSearchFile = shouldCreateOpenSearchFile;
+exports.createOpenSearchFile = createOpenSearchFile;
+exports.createOpenSearchHeadTags = createOpenSearchHeadTags;
+const path_1 = __importDefault(require("path"));
+const eta_1 = require("eta");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const lodash_1 = __importDefault(require("lodash"));
+const opensearch_1 = __importDefault(require("./templates/opensearch"));
+const utils_1 = require("./utils");
+const getCompiledOpenSearchTemplate = lodash_1.default.memoize(() => (0, eta_1.compile)(opensearch_1.default.trim()));
+function renderOpenSearchTemplate(data) {
+    const compiled = getCompiledOpenSearchTemplate();
+    return compiled(data, eta_1.defaultConfig);
+}
+const OPEN_SEARCH_FILENAME = 'opensearch.xml';
+function shouldCreateOpenSearchFile({ context }) {
+    const { siteConfig: { themeConfig, future: { experimental_router: router }, }, } = context;
+    const { algolia: { searchPagePath }, } = themeConfig;
+    return Boolean(searchPagePath) && router !== 'hash';
+}
+function createOpenSearchFileContent({ context, searchPagePath, }) {
+    const { baseUrl, siteConfig: { title, url, favicon }, } = context;
+    const siteUrl = (0, utils_1.normalizeUrl)([url, baseUrl]);
+    return renderOpenSearchTemplate({
+        title,
+        siteUrl,
+        searchUrl: (0, utils_1.normalizeUrl)([siteUrl, searchPagePath]),
+        faviconUrl: favicon ? (0, utils_1.normalizeUrl)([siteUrl, favicon]) : null,
+    });
+}
+async function createOpenSearchFile({ context }) {
+    const { outDir, siteConfig: { themeConfig }, } = context;
+    const { algolia: { searchPagePath }, } = themeConfig;
+    if (!searchPagePath) {
+        throw new Error('no searchPagePath provided in themeConfig.algolia');
+    }
+    const fileContent = createOpenSearchFileContent({ context, searchPagePath });
+    try {
+        await fs_extra_1.default.writeFile(path_1.default.join(outDir, OPEN_SEARCH_FILENAME), fileContent);
+    }
+    catch (err) {
+        const error = new Error('Generating OpenSearch file failed.');
+        error.cause = err;
+        throw error;
+    }
+}
+function createOpenSearchHeadTags({ context }) {
+    const { baseUrl, siteConfig: { title }, } = context;
+    return {
+        tagName: 'link',
+        attributes: {
+            rel: 'search',
+            type: 'application/opensearchdescription+xml',
+            title,
+            href: (0, utils_1.normalizeUrl)([baseUrl, OPEN_SEARCH_FILENAME]),
+        },
+    };
+}

adapters/docusaurus-theme-search-algolia/libtmp/templates/opensearch.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. And its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+declare const _default: "\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<OpenSearchDescription xmlns=\"http://a9.com/-/spec/opensearch/1.1/\"\n                       xmlns:moz=\"http://www.mozilla.org/2006/browser/search/\">\n  <ShortName><%= it.title %></ShortName>\n  <Description>Search <%= it.title %></Description>\n  <InputEncoding>UTF-8</InputEncoding>\n  <% if (it.faviconUrl) { _%>\n    <Image width=\"16\" height=\"16\" type=\"image/x-icon\"><%= it.faviconUrl %></Image>\n  <% } _%>\n  <Url type=\"text/html\" method=\"get\" template=\"<%= it.searchUrl %>?q={searchTerms}\"/>\n  <Url type=\"application/opensearchdescription+xml\" rel=\"self\" template=\"<%= it.siteUrl %>opensearch.xml\" />\n  <moz:SearchForm><%= it.siteUrl %></moz:SearchForm>\n</OpenSearchDescription>\n";
+export default _default;

adapters/docusaurus-theme-search-algolia/libtmp/templates/opensearch.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. And its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = `
+<?xml version="1.0" encoding="UTF-8"?>
+<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
+                       xmlns:moz="http://www.mozilla.org/2006/browser/search/">
+  <ShortName><%= it.title %></ShortName>
+  <Description>Search <%= it.title %></Description>
+  <InputEncoding>UTF-8</InputEncoding>
+  <% if (it.faviconUrl) { _%>
+    <Image width="16" height="16" type="image/x-icon"><%= it.faviconUrl %></Image>
+  <% } _%>
+  <Url type="text/html" method="get" template="<%= it.searchUrl %>?q={searchTerms}"/>
+  <Url type="application/opensearchdescription+xml" rel="self" template="<%= it.siteUrl %>opensearch.xml" />
+  <moz:SearchForm><%= it.siteUrl %></moz:SearchForm>
+</OpenSearchDescription>
+`;

adapters/docusaurus-theme-search-algolia/libtmp/utils/escapeRegexp.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Escapes special characters in a string for use in a regular expression.
+ * Based on escape-string-regexp package.
+ */
+export declare function escapeRegexp(string: string): string;

adapters/docusaurus-theme-search-algolia/libtmp/utils/escapeRegexp.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRegexp = escapeRegexp;
+/**
+ * Escapes special characters in a string for use in a regular expression.
+ * Based on escape-string-regexp package.
+ */
+function escapeRegexp(string) {
+    // Escape characters with special meaning either inside or outside character
+    // sets. Use a simple backslash escape when it's always valid, and a `\xnn`
+    // escape when the simpler form would be disallowed by stricter unicodeness.
+    return string.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&').replace(/-/g, '\\x2d');
+}

adapters/docusaurus-theme-search-algolia/libtmp/utils/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export { normalizeUrl } from './normalizeUrl';
+export { escapeRegexp } from './escapeRegexp';

adapters/docusaurus-theme-search-algolia/libtmp/utils/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRegexp = exports.normalizeUrl = void 0;
+var normalizeUrl_1 = require("./normalizeUrl");
+Object.defineProperty(exports, "normalizeUrl", { enumerable: true, get: function () { return normalizeUrl_1.normalizeUrl; } });
+var escapeRegexp_1 = require("./escapeRegexp");
+Object.defineProperty(exports, "escapeRegexp", { enumerable: true, get: function () { return escapeRegexp_1.escapeRegexp; } });

adapters/docusaurus-theme-search-algolia/libtmp/utils/normalizeUrl.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Much like `path.join`, but much better. Takes an array of URL segments, and
+ * joins them into a reasonable URL.
+ *
+ * - `["file:", "/home", "/user/", "website"]` => `file:///home/user/website`
+ * - `["file://", "home", "/user/", "website"]` => `file://home/user/website` (relative!)
+ * - Remove trailing slash before parameters or hash.
+ * - Replace `?` in query parameters with `&`.
+ * - Dedupe forward slashes in the entire path, avoiding protocol slashes.
+ *
+ * @throws {TypeError} If any of the URL segment is not a string, this throws.
+ */
+export declare function normalizeUrl(rawUrls: string[]): string;