@azerion/bunosaurus-plugin-content-docs 0.0.0-stage → 4.0.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# `@docusaurus/plugin-content-docs`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Docs plugin for Docusaurus.
+
+## Usage
+
+See [plugin-content-docs documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs).

package/lib/categoryGeneratedIndex.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 SidebarsUtils } from './sidebars/utils';
+import type { CategoryGeneratedIndexMetadata, DocMetadataBase } from '@docusaurus/plugin-content-docs';
+export declare function getCategoryGeneratedIndexMetadataList({ docs, sidebarsUtils, }: {
+    sidebarsUtils: SidebarsUtils;
+    docs: DocMetadataBase[];
+}): CategoryGeneratedIndexMetadata[];

package/lib/categoryGeneratedIndex.js

@@ -0,0 +1,36 @@
+"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.getCategoryGeneratedIndexMetadataList = getCategoryGeneratedIndexMetadataList;
+const utils_1 = require("./sidebars/utils");
+const docs_1 = require("./docs");
+function getCategoryGeneratedIndexMetadata({ category, sidebarsUtils, docsById, }) {
+    const { sidebarName, previous, next } = sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
+    return {
+        title: category.link.title ?? category.label,
+        description: category.link.description,
+        image: category.link.image,
+        keywords: category.link.keywords,
+        slug: category.link.slug,
+        permalink: category.link.permalink,
+        sidebar: sidebarName,
+        navigation: {
+            previous: (0, utils_1.toNavigationLink)(previous, docsById),
+            next: (0, utils_1.toNavigationLink)(next, docsById),
+        },
+    };
+}
+function getCategoryGeneratedIndexMetadataList({ docs, sidebarsUtils, }) {
+    const docsById = (0, docs_1.createDocsByIdIndex)(docs);
+    const categoryGeneratedIndexItems = sidebarsUtils.getCategoryGeneratedIndexList();
+    return categoryGeneratedIndexItems.map((category) => getCategoryGeneratedIndexMetadata({
+        category,
+        sidebarsUtils,
+        docsById,
+    }));
+}

package/lib/cli.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { PluginOptions } from '@docusaurus/plugin-content-docs';
+import type { LoadContext } from '@docusaurus/types';
+declare function cliDocsVersionCommand(version: unknown, { id: pluginId, path: docsPath, sidebarPath }: PluginOptions, { siteDir, i18n }: LoadContext): Promise<void>;
+declare const _default: {
+    cliDocsVersionCommand: typeof cliDocsVersionCommand;
+};
+export default _default;

package/lib/cli.js

@@ -0,0 +1,124 @@
+"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 });
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+const fs_1 = require("@docusaurus/fs");
+const files_1 = require("./versions/files");
+const validation_1 = require("./versions/validation");
+const sidebars_1 = require("./sidebars");
+const constants_1 = require("./constants");
+async function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }) {
+    // Load current sidebar and create a new versioned sidebars file (if needed).
+    // Note: we don't need the sidebars file to be normalized: it's ok to let
+    // plugin option changes to impact older, versioned sidebars
+    // We don't validate here, assuming the user has already built the version
+    const sidebars = await (0, sidebars_1.loadSidebarsFile)(sidebarPath);
+    // Do not create a useless versioned sidebars file if sidebars file is empty
+    // or sidebars are disabled/false)
+    const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
+    if (shouldCreateVersionedSidebarFile) {
+        await (0, fs_1.outputFile)((0, files_1.getVersionSidebarsPath)(siteDir, pluginId, version), `${JSON.stringify(sidebars, null, 2)}\n`, 'utf8');
+    }
+}
+// Tests depend on non-default export for mocking.
+async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, sidebarPath }, { siteDir, i18n }) {
+    // It wouldn't be very user-friendly to show a [default] log prefix,
+    // so we use [docs] instead of [default]
+    const pluginIdLogPrefix = pluginId === utils_1.DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
+    try {
+        (0, validation_1.validateVersionName)(version);
+    }
+    catch (err) {
+        logger_1.default.info `${pluginIdLogPrefix}: Invalid version name provided. Try something like: 1.0.0`;
+        throw err;
+    }
+    const versions = (await (0, files_1.readVersionsFile)(siteDir, pluginId)) ?? [];
+    // Check if version already exists.
+    if (versions.includes(version)) {
+        throw new Error(`${pluginIdLogPrefix}: this version already exists! Use a version tag that does not already exist.`);
+    }
+    if (i18n.locales.length > 1) {
+        logger_1.default.info `Versioned docs will be created for the following locales: name=${i18n.locales}`;
+    }
+    await Promise.all(i18n.locales.map(async (locale) => {
+        const localizationDir = node_path_1.default.resolve(siteDir, i18n.path, (0, utils_1.getLocaleConfig)(i18n, locale).path);
+        // Copy docs files.
+        const docsDir = locale === i18n.defaultLocale
+            ? node_path_1.default.resolve(siteDir, docsPath)
+            : (0, files_1.getDocsDirPathLocalized)({
+                localizationDir,
+                pluginId,
+                versionName: constants_1.CURRENT_VERSION_NAME,
+            });
+        if (!(await (0, fs_1.pathExists)(docsDir)) ||
+            (await fs_1.fs.readdir(docsDir)).length === 0) {
+            if (locale === i18n.defaultLocale) {
+                throw new Error(logger_1.default.interpolate `${pluginIdLogPrefix}: no docs found in path=${docsDir}.`);
+            }
+            else {
+                logger_1.default.warn `${pluginIdLogPrefix}: no docs found in path=${docsDir}. Skipping.`;
+                return;
+            }
+        }
+        const newVersionDir = locale === i18n.defaultLocale
+            ? (0, files_1.getVersionDocsDirPath)(siteDir, pluginId, version)
+            : (0, files_1.getDocsDirPathLocalized)({
+                localizationDir,
+                pluginId,
+                versionName: version,
+            });
+        // verbatimSymlinks: keep relative symlinks relative
+        await fs_1.fs.cp(docsDir, newVersionDir, {
+            recursive: true,
+            verbatimSymlinks: true,
+        });
+        // Copy version JSON translation file for this locale
+        // i18n/<l>/docusaurus-plugin-content-docs/current.json => version-v1.json
+        // See https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs#translation-files-location
+        if (locale !== i18n.defaultLocale) {
+            const dir = (0, files_1.getPluginDirPathLocalized)({
+                localizationDir,
+                pluginId,
+            });
+            const sourceFile = node_path_1.default.join(dir, 'current.json');
+            const dest = node_path_1.default.join(dir, `version-${version}.json`);
+            if (await (0, fs_1.pathExists)(sourceFile)) {
+                await fs_1.fs.cp(sourceFile, dest, { verbatimSymlinks: true });
+            }
+            else {
+                logger_1.default.warn `${pluginIdLogPrefix}: i18n translation file does not exist in path=${sourceFile}. Skipping.`;
+            }
+        }
+    }));
+    await createVersionedSidebarFile({
+        siteDir,
+        pluginId,
+        version,
+        sidebarPath,
+    });
+    // Update versions.json file.
+    versions.unshift(version);
+    await (0, fs_1.outputFile)((0, files_1.getVersionsFilePath)(siteDir, pluginId), `${JSON.stringify(versions, null, 2)}\n`);
+    logger_1.default.success `name=${pluginIdLogPrefix}: version name=${version} created!`;
+}
+// TODO try to remove this workaround
+// Why use a default export instead of named exports here?
+// This is only to make Jest mocking happy
+// After upgrading Jest/SWC we got this weird mocking error in extendCli tests
+// "spyOn: Cannot redefine property cliDocsVersionCommand"
+// I tried various workarounds, and it's the only one that worked :/
+// See also:
+// - https://pyk.sh/fixing-typeerror-cannot-redefine-property-x-error-in-jest-tests#heading-solution-2-using-barrel-imports
+// - https://github.com/aelbore/esbuild-jest/issues/26
+// - https://stackoverflow.com/questions/67872622/jest-spyon-not-working-on-index-file-cannot-redefine-property/69951703#69951703
+exports.default = {
+    cliDocsVersionCommand,
+};

package/lib/client/doc.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 ReactNode } from 'react';
+import type { PropDocContent } from '@docusaurus/plugin-content-docs';
+/**
+ * The React context value returned by the `useDoc()` hook.
+ * It contains useful data related to the currently browsed doc.
+ */
+export type DocContextValue = Pick<PropDocContent, 'metadata' | 'frontMatter' | 'toc' | 'assets' | 'contentTitle'>;
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the doc to the children tree.
+ */
+export declare function DocProvider({ children, content, }: {
+    children: ReactNode;
+    content: PropDocContent;
+}): ReactNode;
+/**
+ * Returns the data of the currently browsed doc. Gives access to the doc's MDX
+ * Component, front matter, metadata, TOC, etc. When swizzling a low-level
+ * component (e.g. the "Edit this page" link) and you need some extra metadata,
+ * you don't have to drill the props all the way through the component tree:
+ * simply use this hook instead.
+ */
+export declare function useDoc(): DocContextValue;

package/lib/client/doc.js

@@ -0,0 +1,47 @@
+/**
+ * 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 React, { useMemo, useContext } from 'react';
+import { ReactContextError } from '@docusaurus/theme-common';
+const Context = React.createContext(null);
+/**
+ * Note: we don't use `PropDoc` as context value on purpose. Metadata is
+ * currently stored inside the MDX component, but we may want to change that in
+ * the future. This layer is a good opportunity to decouple storage from
+ * consuming API, potentially allowing us to provide metadata as both props and
+ * route context without duplicating the chunks in the future.
+ */
+function useContextValue(content) {
+    return useMemo(() => ({
+        metadata: content.metadata,
+        frontMatter: content.frontMatter,
+        assets: content.assets,
+        contentTitle: content.contentTitle,
+        toc: content.toc,
+    }), [content]);
+}
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the doc to the children tree.
+ */
+export function DocProvider({ children, content, }) {
+    const contextValue = useContextValue(content);
+    return <Context value={contextValue}>{children}</Context>;
+}
+/**
+ * Returns the data of the currently browsed doc. Gives access to the doc's MDX
+ * Component, front matter, metadata, TOC, etc. When swizzling a low-level
+ * component (e.g. the "Edit this page" link) and you need some extra metadata,
+ * you don't have to drill the props all the way through the component tree:
+ * simply use this hook instead.
+ */
+export function useDoc() {
+    const doc = useContext(Context);
+    if (doc === null) {
+        throw new ReactContextError('DocProvider');
+    }
+    return doc;
+}

package/lib/client/docSidebarItemsExpandedState.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 ReactNode } from 'react';
+type ContextValue = {
+    /**
+     * The item that the user last opened, `null` when there's none open. On
+     * initial render, it will always be `null`, which doesn't necessarily mean
+     * there's no category open (can have 0, 1, or many being initially open).
+     */
+    expandedItem: number | null;
+    /**
+     * Set the currently expanded item, when the user opens one. Set the value to
+     * `null` when the user closes an open category.
+     */
+    setExpandedItem: (a: number | null) => void;
+};
+/**
+ * Should be used to wrap one sidebar category level. This provider syncs the
+ * expanded states of all sibling categories, and categories can choose to
+ * collapse itself if another one is expanded.
+ */
+export declare function DocSidebarItemsExpandedStateProvider({ children, }: {
+    children: ReactNode;
+}): ReactNode;
+export declare function useDocSidebarItemsExpandedState(): ContextValue;
+export {};

package/lib/client/docSidebarItemsExpandedState.js

@@ -0,0 +1,27 @@
+/**
+ * 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 React, { useMemo, useState, useContext } from 'react';
+import { ReactContextError } from '@docusaurus/theme-common';
+const EmptyContext = Symbol('EmptyContext');
+const Context = React.createContext(EmptyContext);
+/**
+ * Should be used to wrap one sidebar category level. This provider syncs the
+ * expanded states of all sibling categories, and categories can choose to
+ * collapse itself if another one is expanded.
+ */
+export function DocSidebarItemsExpandedStateProvider({ children, }) {
+    const [expandedItem, setExpandedItem] = useState(null);
+    const contextValue = useMemo(() => ({ expandedItem, setExpandedItem }), [expandedItem]);
+    return <Context value={contextValue}>{children}</Context>;
+}
+export function useDocSidebarItemsExpandedState() {
+    const value = useContext(Context);
+    if (value === EmptyContext) {
+        throw new ReactContextError('DocSidebarItemsExpandedStateProvider');
+    }
+    return value;
+}

package/lib/client/docsClientUtils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { GlobalPluginData, GlobalVersion, ActivePlugin, ActiveDocContext, DocVersionSuggestions } from '@docusaurus/plugin-content-docs/client';
+import type { UseDataOptions } from '@docusaurus/types';
+export declare function getActivePlugin(allPluginData: {
+    [pluginId: string]: GlobalPluginData;
+}, pathname: string, options?: UseDataOptions): ActivePlugin | undefined;
+export declare const getLatestVersion: (data: GlobalPluginData) => GlobalVersion;
+export declare function getActiveVersion(data: GlobalPluginData, pathname: string): GlobalVersion | undefined;
+export declare function getActiveDocContext(data: GlobalPluginData, pathname: string): ActiveDocContext;
+export declare function getDocVersionSuggestions(data: GlobalPluginData, pathname: string): DocVersionSuggestions;

package/lib/client/docsClientUtils.js

@@ -0,0 +1,86 @@
+/**
+ * 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 { matchPath } from '@docusaurus/router';
+// This code is not part of the api surface, not in ./theme on purpose
+// get the data of the plugin that is currently "active"
+// ie the docs of that plugin are currently browsed
+// it is useful to support multiple docs plugin instances
+export function getActivePlugin(allPluginData, pathname, options = {}) {
+    const activeEntry = Object.entries(allPluginData)
+        // Route sorting: '/android/foo' should match '/android' instead of '/'
+        .sort((a, b) => b[1].path.localeCompare(a[1].path))
+        .find(([, pluginData]) => !!matchPath(pathname, {
+        path: pluginData.path,
+        exact: false,
+        strict: false,
+    }));
+    const activePlugin = activeEntry
+        ? { pluginId: activeEntry[0], pluginData: activeEntry[1] }
+        : undefined;
+    if (!activePlugin && options.failfast) {
+        throw new Error(`Can't find active docs plugin for "${pathname}" pathname, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: ${Object.values(allPluginData)
+            .map((plugin) => plugin.path)
+            .join(', ')}`);
+    }
+    return activePlugin;
+}
+export const getLatestVersion = (data) => data.versions.find((version) => version.isLast);
+export function getActiveVersion(data, pathname) {
+    // Sort paths so that a match-all version like /docs/* is matched last
+    // Otherwise /docs/* would match /docs/1.0.0/* routes
+    // This is simplified but similar to the core sortRoutes() logic
+    const sortedVersions = [...data.versions].sort((a, b) => {
+        if (a.path === b.path) {
+            return 0;
+        }
+        if (a.path.includes(b.path)) {
+            return -1;
+        }
+        if (b.path.includes(a.path)) {
+            return 1;
+        }
+        return 0;
+    });
+    return sortedVersions.find((version) => !!matchPath(pathname, {
+        path: version.path,
+        exact: false,
+        strict: false,
+    }));
+}
+export function getActiveDocContext(data, pathname) {
+    const activeVersion = getActiveVersion(data, pathname);
+    const activeDoc = activeVersion?.docs.find((doc) => !!matchPath(pathname, {
+        path: doc.path,
+        exact: true,
+        strict: false,
+    }));
+    function getAlternateVersionDocs(docId) {
+        const result = {};
+        data.versions.forEach((version) => {
+            version.docs.forEach((doc) => {
+                if (doc.id === docId) {
+                    result[version.name] = doc;
+                }
+            });
+        });
+        return result;
+    }
+    const alternateVersionDocs = activeDoc
+        ? getAlternateVersionDocs(activeDoc.id)
+        : {};
+    return {
+        activeVersion,
+        activeDoc,
+        alternateDocVersions: alternateVersionDocs,
+    };
+}
+export function getDocVersionSuggestions(data, pathname) {
+    const latestVersion = getLatestVersion(data);
+    const activeDocContext = getActiveDocContext(data, pathname);
+    const latestDocSuggestion = activeDocContext.alternateDocVersions[latestVersion.name];
+    return { latestDocSuggestion, latestVersionSuggestion: latestVersion };
+}

package/lib/client/docsPreferredVersion.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 ReactNode } from 'react';
+import { type GlobalVersion } from '@docusaurus/plugin-content-docs/client';
+/**
+ * This is a maybe-layer. If the docs plugin is not enabled, this provider is a
+ * simple pass-through.
+ */
+export declare function DocsPreferredVersionContextProvider({ children, }: {
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Returns a read-write interface to a plugin's preferred version. The
+ * "preferred version" is defined as the last version that the user visited.
+ * For example, if a user is using v3, even when v4 is later published, the user
+ * would still be browsing v3 docs when she opens the website next time. Note,
+ * the `preferredVersion` attribute will always be `null` before mount.
+ */
+export declare function useDocsPreferredVersion(pluginId?: string | undefined): {
+    preferredVersion: GlobalVersion | null;
+    savePreferredVersionName: (versionName: string) => void;
+};
+export declare function useDocsPreferredVersionByPluginId(): {
+    [pluginId: string]: GlobalVersion | null;
+};

package/lib/client/docsPreferredVersion.js

@@ -0,0 +1,124 @@
+/**
+ * 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 React, { useContext, useEffect, useMemo, useState, useCallback, } from 'react';
+import { useAllDocsData, useDocsData, } from '@docusaurus/plugin-content-docs/client';
+import { DEFAULT_PLUGIN_ID } from '@docusaurus/constants';
+import { useThemeConfig } from '@docusaurus/theme-common';
+import { ReactContextError, createStorageSlot } from '@docusaurus/theme-common';
+const storageKey = (pluginId) => `docs-preferred-version-${pluginId}`;
+const DocsPreferredVersionStorage = {
+    save: (pluginId, persistence, versionName) => {
+        createStorageSlot(storageKey(pluginId), { persistence }).set(versionName);
+    },
+    read: (pluginId, persistence) => createStorageSlot(storageKey(pluginId), { persistence }).get(),
+    clear: (pluginId, persistence) => {
+        createStorageSlot(storageKey(pluginId), { persistence }).del();
+    },
+};
+/**
+ * Initial state is always null as we can't read local storage from node SSR
+ */
+const getInitialState = (pluginIds) => Object.fromEntries(pluginIds.map((id) => [id, { preferredVersionName: null }]));
+/**
+ * Read storage for all docs plugins, assigning each doc plugin a preferred
+ * version (if found)
+ */
+function readStorageState({ pluginIds, versionPersistence, allDocsData, }) {
+    /**
+     * The storage value we read might be stale, and belong to a version that does
+     * not exist in the site anymore. In such case, we remove the storage value to
+     * avoid downstream errors.
+     */
+    function restorePluginState(pluginId) {
+        const preferredVersionNameUnsafe = DocsPreferredVersionStorage.read(pluginId, versionPersistence);
+        const pluginData = allDocsData[pluginId];
+        const versionExists = pluginData.versions.some((version) => version.name === preferredVersionNameUnsafe);
+        if (versionExists) {
+            return { preferredVersionName: preferredVersionNameUnsafe };
+        }
+        DocsPreferredVersionStorage.clear(pluginId, versionPersistence);
+        return { preferredVersionName: null };
+    }
+    return Object.fromEntries(pluginIds.map((id) => [id, restorePluginState(id)]));
+}
+function useVersionPersistence() {
+    return useThemeConfig().docs.versionPersistence;
+}
+const Context = React.createContext(null);
+function useContextValue() {
+    const allDocsData = useAllDocsData();
+    const versionPersistence = useVersionPersistence();
+    const pluginIds = useMemo(() => Object.keys(allDocsData), [allDocsData]);
+    // Initial state is empty, as we can't read browser storage in node/SSR
+    const [state, setState] = useState(() => getInitialState(pluginIds));
+    // On mount, we set the state read from browser storage
+    useEffect(() => {
+        setState(readStorageState({ allDocsData, versionPersistence, pluginIds }));
+    }, [allDocsData, versionPersistence, pluginIds]);
+    // The API that we expose to consumer hooks (memo for constant object)
+    const api = useMemo(() => {
+        function savePreferredVersion(pluginId, versionName) {
+            DocsPreferredVersionStorage.save(pluginId, versionPersistence, versionName);
+            setState((s) => ({
+                ...s,
+                [pluginId]: { preferredVersionName: versionName },
+            }));
+        }
+        return {
+            savePreferredVersion,
+        };
+    }, [versionPersistence]);
+    return [state, api];
+}
+function DocsPreferredVersionContextProviderUnsafe({ children, }) {
+    const value = useContextValue();
+    return <Context value={value}>{children}</Context>;
+}
+/**
+ * This is a maybe-layer. If the docs plugin is not enabled, this provider is a
+ * simple pass-through.
+ */
+export function DocsPreferredVersionContextProvider({ children, }) {
+    return (<DocsPreferredVersionContextProviderUnsafe>
+      {children}
+    </DocsPreferredVersionContextProviderUnsafe>);
+}
+function useDocsPreferredVersionContext() {
+    const value = useContext(Context);
+    if (!value) {
+        throw new ReactContextError('DocsPreferredVersionContextProvider');
+    }
+    return value;
+}
+/**
+ * Returns a read-write interface to a plugin's preferred version. The
+ * "preferred version" is defined as the last version that the user visited.
+ * For example, if a user is using v3, even when v4 is later published, the user
+ * would still be browsing v3 docs when she opens the website next time. Note,
+ * the `preferredVersion` attribute will always be `null` before mount.
+ */
+export function useDocsPreferredVersion(pluginId = DEFAULT_PLUGIN_ID) {
+    const docsData = useDocsData(pluginId);
+    const [state, api] = useDocsPreferredVersionContext();
+    const { preferredVersionName } = state[pluginId];
+    const preferredVersion = docsData.versions.find((version) => version.name === preferredVersionName) ?? null;
+    const savePreferredVersionName = useCallback((versionName) => {
+        api.savePreferredVersion(pluginId, versionName);
+    }, [api, pluginId]);
+    return { preferredVersion, savePreferredVersionName };
+}
+export function useDocsPreferredVersionByPluginId() {
+    const allDocsData = useAllDocsData();
+    const [state] = useDocsPreferredVersionContext();
+    function getPluginIdPreferredVersion(pluginId) {
+        const docsData = allDocsData[pluginId];
+        const { preferredVersionName } = state[pluginId];
+        return (docsData.versions.find((version) => version.name === preferredVersionName) ?? null);
+    }
+    const pluginIds = Object.keys(allDocsData);
+    return Object.fromEntries(pluginIds.map((id) => [id, getPluginIdPreferredVersion(id)]));
+}

package/lib/client/docsSearch.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.
+ */
+/** The search tag to append as each doc's metadata. */
+export declare function getDocsVersionSearchTag(pluginId: string, versionName: string): string;
+/**
+ * Gets the relevant docs tags to search.
+ * This is the logic that powers the contextual search feature.
+ *
+ * If user is browsing Android 1.4 docs, he'll get presented with:
+ * - Android '1.4' docs
+ * - iOS 'preferred | latest' docs
+ *
+ * The result is generic and not coupled to Algolia/DocSearch on purpose.
+ */
+export declare function useDocsContextualSearchTags(): string[];

package/lib/client/docsSearch.js

@@ -0,0 +1,39 @@
+/**
+ * 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 { useAllDocsData, useActivePluginAndVersion, } from '@docusaurus/plugin-content-docs/client';
+import { useDocsPreferredVersionByPluginId } from './docsPreferredVersion';
+/** The search tag to append as each doc's metadata. */
+export function getDocsVersionSearchTag(pluginId, versionName) {
+    return `docs-${pluginId}-${versionName}`;
+}
+/**
+ * Gets the relevant docs tags to search.
+ * This is the logic that powers the contextual search feature.
+ *
+ * If user is browsing Android 1.4 docs, he'll get presented with:
+ * - Android '1.4' docs
+ * - iOS 'preferred | latest' docs
+ *
+ * The result is generic and not coupled to Algolia/DocSearch on purpose.
+ */
+export function useDocsContextualSearchTags() {
+    const allDocsData = useAllDocsData();
+    const activePluginAndVersion = useActivePluginAndVersion();
+    const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();
+    // This can't use more specialized hooks because we are mapping over all
+    // plugin instances.
+    function getDocPluginTags(pluginId) {
+        const activeVersion = activePluginAndVersion?.activePlugin.pluginId === pluginId
+            ? activePluginAndVersion.activeVersion
+            : undefined;
+        const preferredVersion = docsPreferredVersionByPluginId[pluginId];
+        const latestVersion = allDocsData[pluginId].versions.find((v) => v.isLast);
+        const version = activeVersion ?? preferredVersion ?? latestVersion;
+        return getDocsVersionSearchTag(pluginId, version.name);
+    }
+    return [...Object.keys(allDocsData).map(getDocPluginTags)];
+}