@docusaurus/plugin-content-docs 2.0.0-beta.15d451942 → 2.0.0-beta.16

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 { CategoryGeneratedIndexMetadata, DocMetadataBase } from './types';
+import { type SidebarsUtils } from './sidebars/utils';
+export declare function getCategoryGeneratedIndexMetadataList({ docs, sidebarsUtils, }: {
+    sidebarsUtils: SidebarsUtils;
+    docs: DocMetadataBase[];
+}): CategoryGeneratedIndexMetadata[];

package/lib/categoryGeneratedIndex.js

@@ -0,0 +1,39 @@
+"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, }) {
+    var _a;
+    const { sidebarName, previous, next } = sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
+    if (!sidebarName) {
+        throw new Error('unexpected');
+    }
+    return {
+        title: (_a = category.link.title) !== null && _a !== void 0 ? _a : category.label,
+        description: category.link.description,
+        image: category.link.image,
+        keywords: category.link.keywords,
+        slug: category.link.slug,
+        permalink: category.link.permalink,
+        sidebar: sidebarName,
+        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,5 @@
  * 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 { PathOptions, SidebarOptions } from '@docusaurus/plugin-content-docs';
+export declare function cliDocsVersionCommand(version: string | null | undefined, siteDir: string, pluginId: string, options: PathOptions & SidebarOptions): Promise<void>;

package/lib/cli.js

@@ -9,94 +9,82 @@ 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 fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const sidebars_1 = require("./sidebars");
-const constants_1 = require("@docusaurus/core/lib/constants");
-function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }) {
+const utils_1 = require("@docusaurus/utils");
+const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+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 versionedSidebarsDir = (0, 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.ensureDir(path_1.default.dirname(newSidebarFile));
+        await fs_extra_1.default.writeFile(newSidebarFile, `${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, siteDir, pluginId, options) {
     // 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}] `;
+    const pluginIdLogPrefix = pluginId === utils_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. Ex: 1.0.0`);
+        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 (\\). Try something like: 1.0.0`);
+        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 must <= 32 characters. Try something like: 1.0.0`);
+        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`);
+        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0.`);
     }
     if (/^\.\.?$/.test(version)) {
-        throw new Error(`${pluginIdLogPrefix}Invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0`);
+        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'));
+    const versionsJSONFile = (0, versions_1.getVersionsFilePath)(siteDir, pluginId);
+    if (await fs_extra_1.default.pathExists(versionsJSONFile)) {
+        versions = JSON.parse(await fs_extra_1.default.readFile(versionsJSONFile, 'utf8'));
     }
     // 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.`);
+        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);
+    if ((await fs_extra_1.default.pathExists(docsDir)) &&
+        (await fs_extra_1.default.readdir(docsDir)).length > 0) {
+        const versionedDir = (0, versions_1.getVersionedDocsDirPath)(siteDir, pluginId);
         const newVersionDir = path_1.default.join(versionedDir, `version-${version}`);
-        fs_extra_1.default.copySync(docsDir, newVersionDir);
+        await fs_extra_1.default.copy(docsDir, newVersionDir);
     }
     else {
-        throw new Error(`${pluginIdLogPrefix}There is no docs to version !`);
+        throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
     }
-    createVersionedSidebarFile({ siteDir, pluginId, version, sidebarPath });
+    await createVersionedSidebarFile({
+        siteDir,
+        pluginId,
+        version,
+        sidebarPath: (0, sidebars_1.resolveSidebarPathOption)(siteDir, 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.ensureDir(path_1.default.dirname(versionsJSONFile));
+    await fs_extra_1.default.writeFile(versionsJSONFile, `${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,9 @@
  * 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;
+import type { GlobalPluginData, GlobalVersion, GetActivePluginOptions, ActivePlugin, ActiveDocContext, DocVersionSuggestions } from '@docusaurus/plugin-content-docs/client';
 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 getLatestVersion: (data: GlobalPluginData) => GlobalVersion;
+export declare const getActiveVersion: (data: GlobalPluginData, pathname: string) => GlobalVersion | undefined;
 export declare const getActiveDocContext: (data: GlobalPluginData, pathname: string) => ActiveDocContext;
-export declare type DocVersionSuggestions = {
-    latestDocSuggestion?: GlobalDoc;
-    latestVersionSuggestion?: GlobalVersion;
-};
 export declare const getDocVersionSuggestions: (data: GlobalPluginData, pathname: string) => DocVersionSuggestions;
-export {};

package/lib/client/docsClientUtils.js

@@ -8,51 +8,52 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDocVersionSuggestions = exports.getActiveDocContext = exports.getActiveVersion = exports.getLatestVersion = exports.getActivePlugin = void 0;
 const router_1 = require("@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
 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,
-        });
-    });
+    const activeEntry = Object.entries(allPluginDatas)
+        // Route sorting: '/android/foo' should match '/android' instead of '/'
+        .sort((a, b) => b[1].path.localeCompare(a[1].path))
+        .find(([, pluginData]) => !!(0, router_1.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(allPluginDatas)
             .map((plugin) => plugin.path)
             .join(', ')}`);
     }
     return activePlugin;
 }
 exports.getActivePlugin = getActivePlugin;
-const getLatestVersion = (data) => {
-    return data.versions.find((version) => version.isLast);
-};
+const getLatestVersion = (data) => 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);
+    const lastVersion = (0, exports.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,
-        });
-    });
+    return orderedVersionsMetadata.find((version) => !!(0, 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, {
+    const activeVersion = (0, exports.getActiveVersion)(data, pathname);
+    const activeDoc = activeVersion === null || activeVersion === void 0 ? void 0 : activeVersion.docs.find((doc) => !!(0, router_1.matchPath)(pathname, {
         path: doc.path,
         exact: true,
         strict: false,
@@ -79,16 +80,9 @@ const getActiveDocContext = (data, pathname) => {
 };
 exports.getActiveDocContext = getActiveDocContext;
 const getDocVersionSuggestions = (data, pathname) => {
-    const latestVersion = exports.getLatestVersion(data);
-    const activeDocContext = exports.getActiveDocContext(data, pathname);
-    // We only suggest another doc/version if user is not using the latest version
-    const isNotOnLatestVersion = activeDocContext.activeVersion !== latestVersion;
-    const latestDocSuggestion = isNotOnLatestVersion
-        ? activeDocContext === null || activeDocContext === void 0 ? void 0 : activeDocContext.alternateDocVersions[latestVersion.name]
-        : undefined;
-    const latestVersionSuggestion = isNotOnLatestVersion
-        ? latestVersion
-        : undefined;
-    return { latestDocSuggestion, latestVersionSuggestion };
+    const latestVersion = (0, exports.getLatestVersion)(data);
+    const activeDocContext = (0, exports.getActiveDocContext)(data, pathname);
+    const latestDocSuggestion = activeDocContext === null || activeDocContext === void 0 ? void 0 : activeDocContext.alternateDocVersions[latestVersion.name];
+    return { latestDocSuggestion, latestVersionSuggestion: latestVersion };
 };
 exports.getDocVersionSuggestions = getDocVersionSuggestions;

package/lib/{theme/hooks/useDocs.d.ts → client/index.d.ts}

@@ -4,8 +4,7 @@
  * 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 } from '../../types';
-import { ActivePlugin, ActiveDocContext, DocVersionSuggestions, GetActivePluginOptions } from '../../client/docsClientUtils';
+import type { GlobalPluginData, GlobalVersion, ActivePlugin, ActiveDocContext, DocVersionSuggestions, GetActivePluginOptions } from '@docusaurus/plugin-content-docs/client';
 export declare const useAllDocsData: () => Record<string, GlobalPluginData>;
 export declare const useDocsData: (pluginId: string | undefined) => GlobalPluginData;
 export declare const useActivePlugin: (options?: GetActivePluginOptions) => ActivePlugin | undefined;

package/lib/client/index.js

@@ -0,0 +1,75 @@
+"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.useDocVersionSuggestions = exports.useActiveDocContext = exports.useActiveVersion = exports.useLatestVersion = exports.useVersions = exports.useActivePluginAndVersion = exports.useActivePlugin = exports.useDocsData = exports.useAllDocsData = void 0;
+const tslib_1 = require("tslib");
+const router_1 = require("@docusaurus/router");
+const useGlobalData_1 = (0, tslib_1.__importStar)(require("@docusaurus/useGlobalData"));
+const docsClientUtils_1 = require("./docsClientUtils");
+// Important to use a constant object to avoid React useEffect executions etc.
+// see https://github.com/facebook/docusaurus/issues/5089
+const StableEmptyObject = {};
+// Not using useAllPluginInstancesData() because 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
+const useAllDocsData = () => { var _a; return (_a = (0, useGlobalData_1.default)()['docusaurus-plugin-content-docs']) !== null && _a !== void 0 ? _a : StableEmptyObject; };
+exports.useAllDocsData = useAllDocsData;
+const useDocsData = (pluginId) => (0, useGlobalData_1.usePluginData)('docusaurus-plugin-content-docs', pluginId);
+exports.useDocsData = useDocsData;
+// TODO this feature should be provided by docusaurus core
+const useActivePlugin = (options = {}) => {
+    const data = (0, exports.useAllDocsData)();
+    const { pathname } = (0, router_1.useLocation)();
+    return (0, docsClientUtils_1.getActivePlugin)(data, pathname, options);
+};
+exports.useActivePlugin = useActivePlugin;
+const useActivePluginAndVersion = (options = {}) => {
+    const activePlugin = (0, exports.useActivePlugin)(options);
+    const { pathname } = (0, router_1.useLocation)();
+    if (activePlugin) {
+        const activeVersion = (0, docsClientUtils_1.getActiveVersion)(activePlugin.pluginData, pathname);
+        return {
+            activePlugin,
+            activeVersion,
+        };
+    }
+    return undefined;
+};
+exports.useActivePluginAndVersion = useActivePluginAndVersion;
+// versions are returned ordered (most recent first)
+const useVersions = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    return data.versions;
+};
+exports.useVersions = useVersions;
+const useLatestVersion = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    return (0, docsClientUtils_1.getLatestVersion)(data);
+};
+exports.useLatestVersion = useLatestVersion;
+// Note: return undefined on doc-unrelated pages,
+// because there's no version currently considered as active
+const useActiveVersion = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    const { pathname } = (0, router_1.useLocation)();
+    return (0, docsClientUtils_1.getActiveVersion)(data, pathname);
+};
+exports.useActiveVersion = useActiveVersion;
+const useActiveDocContext = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    const { pathname } = (0, router_1.useLocation)();
+    return (0, docsClientUtils_1.getActiveDocContext)(data, pathname);
+};
+exports.useActiveDocContext = useActiveDocContext;
+// Useful to say "hey, you are not on the latest docs version, please switch"
+const useDocVersionSuggestions = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    const { pathname } = (0, router_1.useLocation)();
+    return (0, docsClientUtils_1.getDocVersionSuggestions)(data, pathname);
+};
+exports.useDocVersionSuggestions = useDocVersionSuggestions;

package/lib/docFrontMatter.d.ts

@@ -4,18 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export declare type DocFrontMatter = {
-    id?: string;
-    title?: string;
-    hide_title?: boolean;
-    hide_table_of_contents?: boolean;
-    keywords?: string[];
-    image?: string;
-    description?: string;
-    slug?: string;
-    sidebar_label?: string;
-    sidebar_position?: number;
-    custom_edit_url?: string | null;
-    parse_number_prefixes?: boolean;
-};
+import type { DocFrontMatter } from './types';
 export declare function validateDocFrontMatter(frontMatter: Record<string, unknown>): DocFrontMatter;

package/lib/docFrontMatter.js

@@ -7,10 +7,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateDocFrontMatter = void 0;
-/* eslint-disable camelcase */
 const utils_validation_1 = require("@docusaurus/utils-validation");
 // NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
+// We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
 const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
@@ -19,15 +18,23 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     hide_title: utils_validation_1.JoiFrontMatter.boolean(),
     hide_table_of_contents: utils_validation_1.JoiFrontMatter.boolean(),
     keywords: utils_validation_1.JoiFrontMatter.array().items(utils_validation_1.JoiFrontMatter.string().required()),
-    image: utils_validation_1.JoiFrontMatter.string().uri({ allowRelative: false }),
+    image: utils_validation_1.URISchema,
     description: utils_validation_1.JoiFrontMatter.string().allow(''),
     slug: utils_validation_1.JoiFrontMatter.string(),
     sidebar_label: utils_validation_1.JoiFrontMatter.string(),
-    sidebar_position: utils_validation_1.JoiFrontMatter.number().min(0),
-    custom_edit_url: utils_validation_1.JoiFrontMatter.string().uri({ allowRelative: true }).allow('', null),
+    sidebar_position: utils_validation_1.JoiFrontMatter.number(),
+    sidebar_class_name: utils_validation_1.JoiFrontMatter.string(),
+    sidebar_custom_props: utils_validation_1.JoiFrontMatter.object().unknown(),
+    displayed_sidebar: utils_validation_1.JoiFrontMatter.string().allow(null),
+    tags: utils_validation_1.FrontMatterTagsSchema,
+    pagination_label: utils_validation_1.JoiFrontMatter.string(),
+    custom_edit_url: utils_validation_1.URISchema.allow('', null),
     parse_number_prefixes: utils_validation_1.JoiFrontMatter.boolean(),
+    pagination_next: utils_validation_1.JoiFrontMatter.string().allow(null),
+    pagination_prev: utils_validation_1.JoiFrontMatter.string().allow(null),
+    ...utils_validation_1.FrontMatterTOCHeadingLevels,
 }).unknown();
 function validateDocFrontMatter(frontMatter) {
-    return utils_validation_1.validateFrontMatter(frontMatter, DocFrontMatterSchema);
+    return (0, utils_validation_1.validateFrontMatter)(frontMatter, DocFrontMatterSchema);
 }
 exports.validateDocFrontMatter = validateDocFrontMatter;

package/lib/docs.d.ts

@@ -4,15 +4,51 @@
  * 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';
+import type { LoadContext } from '@docusaurus/types';
+import type { DocFile, DocMetadataBase, VersionMetadata, LoadedVersion } from './types';
+import type { SidebarsUtils } from './sidebars/utils';
+import type { MetadataOptions, PluginOptions, CategoryIndexMatcher, CategoryIndexMatcherParam } from '@docusaurus/plugin-content-docs';
 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[]>;
-export declare function processDocMetadata({ docFile, versionMetadata, context, options, }: {
+export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
+export declare function processDocMetadata(args: {
     docFile: DocFile;
     versionMetadata: VersionMetadata;
     context: LoadContext;
     options: MetadataOptions;
 }): 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;
+export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): CategoryIndexMatcherParam;
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
+export declare function splitPath(str: string): {
+    /**
+     * The list of directories, from lowest level to highest.
+     * If there's no dir name, directories is ['.']
+     */
+    directories: string[];
+    /** The file name, without extension */
+    fileName: string;
+    /** The extension, with a leading dot */
+    extension: string;
+};
+export declare function getDocIds(doc: DocMetadataBase): [string, string];
+export declare function createDocsByIdIndex<Doc extends {
+    id: string;
+    unversionedId: string;
+}>(docs: Doc[]): Record<string, Doc>;
 export {};