@docusaurus/plugin-content-docs 2.0.0-beta.fbdeefcac → 2.0.0-rc.1

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,37 @@
+"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 = void 0;
+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,
+    }));
+}
+exports.getCategoryGeneratedIndexMetadataList = getCategoryGeneratedIndexMetadataList;

package/lib/cli.d.ts

@@ -4,5 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { PathOptions } from './types';
-export declare function cliDocsVersionCommand(version: string | null | undefined, siteDir: string, pluginId: string, options: PathOptions): void;
+import type { PluginOptions } from '@docusaurus/plugin-content-docs';
+import type { LoadContext } from '@docusaurus/types';
+export declare function cliDocsVersionCommand(version: unknown, { id: pluginId, path: docsPath, sidebarPath }: PluginOptions, { siteDir, i18n }: LoadContext): Promise<void>;

package/lib/cli.js

@@ -8,100 +8,85 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cliDocsVersionCommand = void 0;
 const tslib_1 = require("tslib");
-const versions_1 = require("./versions");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const path_1 = tslib_1.__importDefault(require("path"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+const files_1 = require("./versions/files");
+const validation_1 = require("./versions/validation");
 const sidebars_1 = require("./sidebars");
-const constants_1 = require("@docusaurus/core/lib/constants");
-function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }) {
+const constants_1 = require("./constants");
+async function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }) {
     // Load current sidebar and create a new versioned sidebars file (if needed).
-    const loadedSidebars = sidebars_1.loadSidebars(sidebarPath);
-    // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
-    const shouldCreateVersionedSidebarFile = Object.keys(loadedSidebars).length > 0;
+    // 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.loadSidebarsFileUnsafe)(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) {
-        // TODO @slorber: this "version prefix" in versioned sidebars looks like a bad idea to me
-        // TODO try to get rid of it
-        // Transform id in original sidebar to versioned id.
-        const normalizeItem = (item) => {
-            switch (item.type) {
-                case 'category':
-                    return { ...item, items: item.items.map(normalizeItem) };
-                case 'ref':
-                case 'doc':
-                    return {
-                        type: item.type,
-                        id: `version-${version}/${item.id}`,
-                    };
-                default:
-                    return item;
-            }
-        };
-        const versionedSidebar = Object.entries(loadedSidebars).reduce((acc, [sidebarId, sidebarItems]) => {
-            const newVersionedSidebarId = `version-${version}/${sidebarId}`;
-            acc[newVersionedSidebarId] = sidebarItems.map(normalizeItem);
-            return acc;
-        }, {});
-        const versionedSidebarsDir = versions_1.getVersionedSidebarsDirPath(siteDir, pluginId);
-        const newSidebarFile = path_1.default.join(versionedSidebarsDir, `version-${version}-sidebars.json`);
-        fs_extra_1.default.ensureDirSync(path_1.default.dirname(newSidebarFile));
-        fs_extra_1.default.writeFileSync(newSidebarFile, `${JSON.stringify(versionedSidebar, null, 2)}\n`, 'utf8');
+        await fs_extra_1.default.outputFile((0, files_1.getVersionSidebarsPath)(siteDir, pluginId, version), `${JSON.stringify(sidebars, null, 2)}\n`, 'utf8');
     }
 }
 // Tests depend on non-default export for mocking.
-// eslint-disable-next-line import/prefer-default-export
-function cliDocsVersionCommand(version, siteDir, pluginId, options) {
+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 === constants_1.DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
-    if (!version) {
-        throw new Error(`${pluginIdLogPrefix}: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0.`);
-    }
-    if (version.includes('/') || version.includes('\\')) {
-        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Do not include slash (/) or backslash (\\). Try something like: 1.0.0.`);
-    }
-    if (version.length > 32) {
-        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Length cannot exceed 32 characters. Try something like: 1.0.0.`);
-    }
-    // Since we are going to create `version-${version}` folder, we need to make
-    // sure it's a valid pathname.
-    // eslint-disable-next-line no-control-regex
-    if (/[<>:"|?*\x00-\x1F]/g.test(version)) {
-        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0.`);
+    const pluginIdLogPrefix = pluginId === utils_1.DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
+    try {
+        (0, validation_1.validateVersionName)(version);
     }
-    if (/^\.\.?$/.test(version)) {
-        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0.`);
-    }
-    // Load existing versions.
-    let versions = [];
-    const versionsJSONFile = versions_1.getVersionsFilePath(siteDir, pluginId);
-    if (fs_extra_1.default.existsSync(versionsJSONFile)) {
-        versions = JSON.parse(fs_extra_1.default.readFileSync(versionsJSONFile, 'utf8'));
+    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.`);
     }
-    const { path: docsPath, sidebarPath } = options;
-    // Copy docs files.
-    const docsDir = path_1.default.join(siteDir, docsPath);
-    if (fs_extra_1.default.existsSync(docsDir) && fs_extra_1.default.readdirSync(docsDir).length > 0) {
-        const versionedDir = versions_1.getVersionedDocsDirPath(siteDir, pluginId);
-        const newVersionDir = path_1.default.join(versionedDir, `version-${version}`);
-        fs_extra_1.default.copySync(docsDir, newVersionDir);
-    }
-    else {
-        throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
+    if (i18n.locales.length > 1) {
+        logger_1.default.info `Versioned docs will be created for the following locales: name=${i18n.locales}`;
     }
-    createVersionedSidebarFile({
+    await Promise.all(i18n.locales.map(async (locale) => {
+        const localizationDir = path_1.default.resolve(siteDir, i18n.path, i18n.localeConfigs[locale].path);
+        // Copy docs files.
+        const docsDir = locale === i18n.defaultLocale
+            ? path_1.default.resolve(siteDir, docsPath)
+            : (0, files_1.getDocsDirPathLocalized)({
+                localizationDir,
+                pluginId,
+                versionName: constants_1.CURRENT_VERSION_NAME,
+            });
+        if (!(await fs_extra_1.default.pathExists(docsDir)) ||
+            (await fs_extra_1.default.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,
+            });
+        await fs_extra_1.default.copy(docsDir, newVersionDir);
+    }));
+    await createVersionedSidebarFile({
         siteDir,
         pluginId,
         version,
-        sidebarPath: sidebars_1.resolveSidebarPathOption(siteDir, sidebarPath),
+        sidebarPath,
     });
     // Update versions.json file.
     versions.unshift(version);
-    fs_extra_1.default.ensureDirSync(path_1.default.dirname(versionsJSONFile));
-    fs_extra_1.default.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
-    console.log(`${pluginIdLogPrefix}: version ${version} created!`);
+    await fs_extra_1.default.outputFile((0, files_1.getVersionsFilePath)(siteDir, pluginId), `${JSON.stringify(versions, null, 2)}\n`);
+    logger_1.default.success `name=${pluginIdLogPrefix}: version name=${version} created!`;
 }
 exports.cliDocsVersionCommand = cliDocsVersionCommand;

package/lib/client/docsClientUtils.d.ts

@@ -4,31 +4,12 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { GlobalPluginData, GlobalVersion, GlobalDoc } from '../types';
-declare type Version = GlobalVersion;
-declare type Doc = GlobalDoc;
-export declare type ActivePlugin = {
-    pluginId: string;
-    pluginData: GlobalPluginData;
-};
-export declare type GetActivePluginOptions = {
-    failfast?: boolean;
-};
-export declare function getActivePlugin(allPluginDatas: Record<string, GlobalPluginData>, pathname: string, options: {
-    failfast: true;
-}): ActivePlugin;
-export declare function getActivePlugin(allPluginDatas: Record<string, GlobalPluginData>, pathname: string, options?: GetActivePluginOptions): ActivePlugin | undefined;
-export declare type ActiveDocContext = {
-    activeVersion?: Version;
-    activeDoc?: Doc;
-    alternateDocVersions: Record<string, Doc>;
-};
-export declare const getLatestVersion: (data: GlobalPluginData) => Version;
-export declare const getActiveVersion: (data: GlobalPluginData, pathname: string) => Version | undefined;
-export declare const getActiveDocContext: (data: GlobalPluginData, pathname: string) => ActiveDocContext;
-export declare type DocVersionSuggestions = {
-    latestVersionSuggestion: GlobalVersion;
-    latestDocSuggestion?: GlobalDoc;
-};
-export declare const getDocVersionSuggestions: (data: GlobalPluginData, pathname: string) => DocVersionSuggestions;
-export {};
+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

@@ -1,58 +1,51 @@
-"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.getDocVersionSuggestions = exports.getActiveDocContext = exports.getActiveVersion = exports.getLatestVersion = exports.getActivePlugin = void 0;
-const router_1 = require("@docusaurus/router");
-function getActivePlugin(allPluginDatas, pathname, options = {}) {
-    const activeEntry = Object.entries(allPluginDatas).find(([_id, pluginData]) => {
-        return !!router_1.matchPath(pathname, {
-            path: pluginData.path,
-            exact: false,
-            strict: false,
-        });
-    });
+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(allPluginDatas)
+        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;
 }
-exports.getActivePlugin = getActivePlugin;
-const getLatestVersion = (data) => {
-    return data.versions.find((version) => version.isLast);
-};
-exports.getLatestVersion = getLatestVersion;
-// Note: return undefined on doc-unrelated pages,
-// because there's no version currently considered as active
-const getActiveVersion = (data, pathname) => {
-    const lastVersion = exports.getLatestVersion(data);
+export const getLatestVersion = (data) => data.versions.find((version) => version.isLast);
+export function getActiveVersion(data, pathname) {
+    const lastVersion = getLatestVersion(data);
     // Last version is a route like /docs/*,
-    // we need to try to match it last or it would match /docs/version-1.0/* as well
+    // we need to match it last or it would match /docs/version-1.0/* as well
     const orderedVersionsMetadata = [
         ...data.versions.filter((version) => version !== lastVersion),
         lastVersion,
     ];
-    return orderedVersionsMetadata.find((version) => {
-        return !!router_1.matchPath(pathname, {
-            path: version.path,
-            exact: false,
-            strict: false,
-        });
-    });
-};
-exports.getActiveVersion = getActiveVersion;
-const getActiveDocContext = (data, pathname) => {
-    const activeVersion = exports.getActiveVersion(data, pathname);
-    const activeDoc = activeVersion === null || activeVersion === void 0 ? void 0 : activeVersion.docs.find((doc) => !!router_1.matchPath(pathname, {
+    return orderedVersionsMetadata.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,
@@ -76,12 +69,10 @@ const getActiveDocContext = (data, pathname) => {
         activeDoc,
         alternateDocVersions: alternateVersionDocs,
     };
-};
-exports.getActiveDocContext = getActiveDocContext;
-const getDocVersionSuggestions = (data, pathname) => {
-    const latestVersion = exports.getLatestVersion(data);
-    const activeDocContext = exports.getActiveDocContext(data, pathname);
-    const latestDocSuggestion = activeDocContext === null || activeDocContext === void 0 ? void 0 : activeDocContext.alternateDocVersions[latestVersion.name];
+}
+export function getDocVersionSuggestions(data, pathname) {
+    const latestVersion = getLatestVersion(data);
+    const activeDocContext = getActiveDocContext(data, pathname);
+    const latestDocSuggestion = activeDocContext.alternateDocVersions[latestVersion.name];
     return { latestDocSuggestion, latestVersionSuggestion: latestVersion };
-};
-exports.getDocVersionSuggestions = getDocVersionSuggestions;
+}

package/lib/client/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 { UseDataOptions } from '@docusaurus/types';
+export declare type ActivePlugin = {
+    pluginId: string;
+    pluginData: GlobalPluginData;
+};
+export declare type ActiveDocContext = {
+    activeVersion?: GlobalVersion;
+    activeDoc?: GlobalDoc;
+    alternateDocVersions: {
+        [versionName: string]: GlobalDoc;
+    };
+};
+export declare type GlobalDoc = {
+    /**
+     * For generated index pages, this is the `slug`, **not** `permalink`
+     * (without base URL). Because slugs have leading slashes but IDs don't,
+     * there won't be clashes.
+     */
+    id: string;
+    path: string;
+    sidebar: string | undefined;
+};
+export declare type GlobalVersion = {
+    name: string;
+    label: string;
+    isLast: boolean;
+    path: string;
+    /** The doc with `slug: /`, or first doc in first sidebar */
+    mainDocId: string;
+    docs: GlobalDoc[];
+    /** Unversioned IDs. In development, this list is empty. */
+    draftIds: string[];
+    sidebars?: {
+        [sidebarId: string]: GlobalSidebar;
+    };
+};
+export declare type GlobalSidebar = {
+    link?: {
+        label: string;
+        path: string;
+    };
+};
+export declare type GlobalPluginData = {
+    path: string;
+    versions: GlobalVersion[];
+    breadcrumbs: boolean;
+};
+export declare type DocVersionSuggestions = {
+    /** Suggest the latest version */
+    latestVersionSuggestion: GlobalVersion;
+    /** Suggest the same doc, in latest version (if one exists) */
+    latestDocSuggestion?: GlobalDoc;
+};
+export declare const useAllDocsData: () => {
+    [pluginId: string]: GlobalPluginData;
+};
+export declare const useDocsData: (pluginId: string | undefined) => GlobalPluginData;
+export declare function useActivePlugin(options?: UseDataOptions): ActivePlugin | undefined;
+export declare function useActivePluginAndVersion(options?: UseDataOptions): {
+    activePlugin: ActivePlugin;
+    activeVersion: GlobalVersion | undefined;
+} | undefined;
+/** Versions are returned ordered (most recent first). */
+export declare function useVersions(pluginId: string | undefined): GlobalVersion[];
+export declare function useLatestVersion(pluginId: string | undefined): GlobalVersion;
+/**
+ * Returns `undefined` on doc-unrelated pages, because there's no version
+ * currently considered as active.
+ */
+export declare function useActiveVersion(pluginId: string | undefined): GlobalVersion | undefined;
+export declare function useActiveDocContext(pluginId: string | undefined): ActiveDocContext;
+/**
+ * Useful to say "hey, you are not on the latest docs version, please switch"
+ */
+export declare function useDocVersionSuggestions(pluginId: string | undefined): DocVersionSuggestions;

package/lib/client/index.js

@@ -0,0 +1,67 @@
+/**
+ * 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 { useLocation } from '@docusaurus/router';
+import { useAllPluginInstancesData, usePluginData, } from '@docusaurus/useGlobalData';
+import { getActivePlugin, getLatestVersion, getActiveVersion, getActiveDocContext, getDocVersionSuggestions, } from './docsClientUtils';
+// Important to use a constant object to avoid React useEffect executions etc.
+// see https://github.com/facebook/docusaurus/issues/5089
+const StableEmptyObject = {};
+// In blog-only mode, docs hooks are still used by the theme. We need a fail-
+// safe fallback when the docs plugin is not in use
+export const useAllDocsData = () => useAllPluginInstancesData('docusaurus-plugin-content-docs') ?? StableEmptyObject;
+export const useDocsData = (pluginId) => usePluginData('docusaurus-plugin-content-docs', pluginId, {
+    failfast: true,
+});
+// TODO this feature should be provided by docusaurus core
+export function useActivePlugin(options = {}) {
+    const data = useAllDocsData();
+    const { pathname } = useLocation();
+    return getActivePlugin(data, pathname, options);
+}
+export function useActivePluginAndVersion(options = {}) {
+    const activePlugin = useActivePlugin(options);
+    const { pathname } = useLocation();
+    if (!activePlugin) {
+        return undefined;
+    }
+    const activeVersion = getActiveVersion(activePlugin.pluginData, pathname);
+    return {
+        activePlugin,
+        activeVersion,
+    };
+}
+/** Versions are returned ordered (most recent first). */
+export function useVersions(pluginId) {
+    const data = useDocsData(pluginId);
+    return data.versions;
+}
+export function useLatestVersion(pluginId) {
+    const data = useDocsData(pluginId);
+    return getLatestVersion(data);
+}
+/**
+ * Returns `undefined` on doc-unrelated pages, because there's no version
+ * currently considered as active.
+ */
+export function useActiveVersion(pluginId) {
+    const data = useDocsData(pluginId);
+    const { pathname } = useLocation();
+    return getActiveVersion(data, pathname);
+}
+export function useActiveDocContext(pluginId) {
+    const data = useDocsData(pluginId);
+    const { pathname } = useLocation();
+    return getActiveDocContext(data, pathname);
+}
+/**
+ * Useful to say "hey, you are not on the latest docs version, please switch"
+ */
+export function useDocVersionSuggestions(pluginId) {
+    const data = useDocsData(pluginId);
+    const { pathname } = useLocation();
+    return getDocVersionSuggestions(data, pathname);
+}

package/lib/constants.d.ts

@@ -4,7 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/** The name of the version that's actively worked on (e.g. `website/docs`) */
 export declare const CURRENT_VERSION_NAME = "current";
+/** All doc versions are stored here by version names */
 export declare const VERSIONED_DOCS_DIR = "versioned_docs";
+/** All doc versioned sidebars are stored here by version names */
 export declare const VERSIONED_SIDEBARS_DIR = "versioned_sidebars";
+/** The version names. Should 1-1 map to the content of versioned docs dir. */
 export declare const VERSIONS_JSON_FILE = "versions.json";

package/lib/constants.js

@@ -7,8 +7,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSIONS_JSON_FILE = exports.VERSIONED_SIDEBARS_DIR = exports.VERSIONED_DOCS_DIR = exports.CURRENT_VERSION_NAME = void 0;
-// The name of the version at the root of your site (website/docs)
+/** The name of the version that's actively worked on (e.g. `website/docs`) */
 exports.CURRENT_VERSION_NAME = 'current';
+/** All doc versions are stored here by version names */
 exports.VERSIONED_DOCS_DIR = 'versioned_docs';
+/** All doc versioned sidebars are stored here by version names */
 exports.VERSIONED_SIDEBARS_DIR = 'versioned_sidebars';
+/** The version names. Should 1-1 map to the content of versioned docs dir. */
 exports.VERSIONS_JSON_FILE = 'versions.json';

package/lib/docs.d.ts

@@ -4,15 +4,42 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { LoadContext } from '@docusaurus/types';
-import { DocFile, DocMetadataBase, MetadataOptions, PluginOptions, VersionMetadata } from './types';
-declare type LastUpdateOptions = Pick<PluginOptions, 'showLastUpdateAuthor' | 'showLastUpdateTime'>;
-export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string, options: LastUpdateOptions): Promise<DocFile>;
-export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
+import type { MetadataOptions, PluginOptions, CategoryIndexMatcher, DocMetadataBase, VersionMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
+import type { LoadContext } from '@docusaurus/types';
+import type { SidebarsUtils } from './sidebars/utils';
+import type { DocFile } from './types';
+export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string): Promise<DocFile>;
+export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
+export declare type DocEnv = 'production' | 'development';
 export declare function processDocMetadata(args: {
     docFile: DocFile;
     versionMetadata: VersionMetadata;
     context: LoadContext;
     options: MetadataOptions;
-}): DocMetadataBase;
-export {};
+    env: DocEnv;
+}): Promise<DocMetadataBase>;
+export declare function addDocNavigation(docsBase: DocMetadataBase[], sidebarsUtils: SidebarsUtils, sidebarFilePath: string): LoadedVersion['docs'];
+/**
+ * The "main doc" is the "version entry point"
+ * We browse this doc by clicking on a version:
+ * - the "home" doc (at '/docs/')
+ * - the first doc of the first sidebar
+ * - a random doc (if no docs are in any sidebar... edge case)
+ */
+export declare function getMainDocId({ docs, sidebarsUtils, }: {
+    docs: DocMetadataBase[];
+    sidebarsUtils: SidebarsUtils;
+}): string;
+export declare const isCategoryIndex: CategoryIndexMatcher;
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
+export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): Parameters<CategoryIndexMatcher>[0];
+export declare function getDocIds(doc: DocMetadataBase): [string, string];
+export declare function createDocsByIdIndex<Doc extends {
+    id: string;
+    unversionedId: string;
+}>(docs: Doc[]): {
+    [docId: string]: Doc;
+};