@docusaurus/plugin-content-docs 0.0.0-4240 → 0.0.0-4244

package/lib/sidebars/generator.js

@@ -10,33 +10,31 @@ exports.DefaultSidebarItemsGenerator = exports.CategoryMetadataFilenamePattern =
 const tslib_1 = require("tslib");
 const lodash_1 = require("lodash");
 const utils_1 = require("@docusaurus/utils");
-const utils_validation_1 = require("@docusaurus/utils-validation");
 const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
 const js_yaml_1 = (0, tslib_1.__importDefault)(require("js-yaml"));
+const validation_1 = require("./validation");
+const docs_1 = require("../docs");
 const BreadcrumbSeparator = '/';
 // To avoid possible name clashes with a folder of the same name as the ID
 const docIdPrefix = '$doc$/';
+// Just an alias to the make code more explicit
+function getLocalDocId(docId) {
+    return (0, lodash_1.last)(docId.split('/'));
+}
 exports.CategoryMetadataFilenameBase = '_category_';
 exports.CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
-const CategoryMetadataFileSchema = utils_validation_1.Joi.object({
-    label: utils_validation_1.Joi.string(),
-    position: utils_validation_1.Joi.number(),
-    collapsed: utils_validation_1.Joi.boolean(),
-    collapsible: utils_validation_1.Joi.boolean(),
-    className: utils_validation_1.Joi.string(),
-});
 // TODO I now believe we should read all the category metadata files ahead of time: we may need this metadata to customize docs metadata
 // Example use-case being able to disable number prefix parsing at the folder level, or customize the default route path segment for an intermediate directory...
-// TODO later if there is `CategoryFolder/index.md`, we may want to read the metadata as yaml on it
+// TODO later if there is `CategoryFolder/with-category-name-doc.md`, we may want to read the metadata as yaml on it
 // see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
 async function readCategoryMetadataFile(categoryDirPath) {
     async function tryReadFile(filePath) {
         const contentString = await fs_extra_1.default.readFile(filePath, { encoding: 'utf8' });
         const unsafeContent = js_yaml_1.default.load(contentString);
         try {
-            return utils_validation_1.Joi.attempt(unsafeContent, CategoryMetadataFileSchema);
+            return (0, validation_1.validateCategoryMetadataFile)(unsafeContent);
         }
         catch (e) {
             console.error(chalk_1.default.red(`The docs sidebar category metadata file looks invalid!\nPath: ${filePath}`));
@@ -55,6 +53,15 @@ async function readCategoryMetadataFile(categoryDirPath) {
 }
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
 const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs, options, item: { dirName: autogenDir }, version, }) => {
+    const docsById = (0, docs_1.createDocsByIdIndex)(allDocs);
+    const findDoc = (docId) => docsById[docId];
+    const getDoc = (docId) => {
+        const doc = findDoc(docId);
+        if (!doc) {
+            throw new Error(`Can't find any doc with id=${docId}.\nAvailable doc ids:\n- ${Object.keys(docsById).join('\n- ')}`);
+        }
+        return doc;
+    };
     /**
      * Step 1. Extract the docs that are in the autogen dir.
      */
@@ -110,9 +117,8 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs,
      * (From a record to an array of items, akin to normalizing shorthand)
      */
     function generateSidebar(fsModel) {
-        const docsById = (0, lodash_1.keyBy)(allDocs, (doc) => doc.id);
         function createDocItem(id) {
-            const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className }, } = docsById[id];
+            const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className }, } = getDoc(id);
             return {
                 type: 'doc',
                 id,
@@ -128,6 +134,41 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs,
             const categoryMetadata = await readCategoryMetadataFile(categoryPath);
             const className = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.className;
             const { filename, numberPrefix } = numberPrefixParser(folderName);
+            const allItems = await Promise.all(Object.entries(dir).map(([key, content]) => dirToItem(content, key, `${fullPath}/${key}`)));
+            // Try to match a doc inside the category folder,
+            // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
+            function findDocByLocalId(localId) {
+                return allItems.find((item) => item.type === 'doc' && getLocalDocId(item.id) === localId);
+            }
+            function findConventionalCategoryDocLink() {
+                return allItems.find((item) => item.type === 'doc' && (0, docs_1.isConventionalDocIndex)(getDoc(item.id)));
+            }
+            function getCategoryLinkedDocId() {
+                var _a, _b;
+                const link = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.link;
+                if (link) {
+                    if (link.type === 'doc') {
+                        return ((_a = findDocByLocalId(link.id)) === null || _a === void 0 ? void 0 : _a.id) || getDoc(link.id).id;
+                    }
+                    else {
+                        // We don't continue for other link types on purpose!
+                        // IE if user decide to use type "generated-index", we should not pick a README.md file as the linked doc
+                        return undefined;
+                    }
+                }
+                // Apply default convention to pick index.md, README.md or <categoryName>.md as the category doc
+                return (_b = findConventionalCategoryDocLink()) === null || _b === void 0 ? void 0 : _b.id;
+            }
+            const categoryLinkedDocId = getCategoryLinkedDocId();
+            const link = categoryLinkedDocId
+                ? {
+                    type: 'doc',
+                    id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
+                }
+                : // TODO typing issue
+                    categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.link;
+            // If a doc is linked, remove it from the category subItems
+            const items = allItems.filter((item) => !(item.type === 'doc' && item.id === categoryLinkedDocId));
             return {
                 type: 'category',
                 label: (_a = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.label) !== null && _a !== void 0 ? _a : filename,
@@ -135,7 +176,8 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs,
                 collapsed: (_c = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.collapsed) !== null && _c !== void 0 ? _c : options.sidebarCollapsed,
                 position: (_d = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.position) !== null && _d !== void 0 ? _d : numberPrefix,
                 ...(className !== undefined && { className }),
-                items: await Promise.all(Object.entries(dir).map(([key, content]) => dirToItem(content, key, `${fullPath}/${key}`))),
+                items,
+                ...(link && { link }),
             };
         }
         async function dirToItem(dir, // The directory item to be transformed.

package/lib/sidebars/index.d.ts

@@ -5,10 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { SidebarsConfig, Sidebars, NormalizedSidebars } from './types';
-import type { PluginOptions } from '../types';
-import { SidebarProcessorProps } from './processor';
+import type { NormalizeSidebarsParams, PluginOptions } from '../types';
+import { SidebarProcessorParams } from './processor';
 export declare const DefaultSidebars: SidebarsConfig;
 export declare const DisabledSidebars: SidebarsConfig;
 export declare function resolveSidebarPathOption(siteDir: string, sidebarPathOption: PluginOptions['sidebarPath']): PluginOptions['sidebarPath'];
-export declare function loadUnprocessedSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorProps['options']): NormalizedSidebars;
-export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorProps): Promise<Sidebars>;
+export declare function loadSidebarsFile(sidebarFilePath: string | false | undefined): SidebarsConfig;
+export declare function loadNormalizedSidebars(sidebarFilePath: string | false | undefined, params: NormalizeSidebarsParams): NormalizedSidebars;
+export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorParams): Promise<Sidebars>;

package/lib/sidebars/index.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadSidebars = exports.loadUnprocessedSidebars = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = void 0;
+exports.loadSidebars = exports.loadNormalizedSidebars = exports.loadSidebarsFile = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = void 0;
 const tslib_1 = require("tslib");
 const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
 const import_fresh_1 = (0, tslib_1.__importDefault)(require("import-fresh"));
@@ -14,6 +14,7 @@ const validation_1 = require("./validation");
 const normalization_1 = require("./normalization");
 const processor_1 = require("./processor");
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
+const utils_1 = require("@docusaurus/utils");
 exports.DefaultSidebars = {
     defaultSidebar: [
         {
@@ -31,7 +32,7 @@ function resolveSidebarPathOption(siteDir, sidebarPathOption) {
         : sidebarPathOption;
 }
 exports.resolveSidebarPathOption = resolveSidebarPathOption;
-function loadSidebarFile(sidebarFilePath) {
+function loadSidebarsFileUnsafe(sidebarFilePath) {
     // false => no sidebars
     if (sidebarFilePath === false) {
         return exports.DisabledSidebars;
@@ -49,16 +50,24 @@ function loadSidebarFile(sidebarFilePath) {
     // We don't want sidebars to be cached because of hot reloading.
     return (0, import_fresh_1.default)(sidebarFilePath);
 }
-function loadUnprocessedSidebars(sidebarFilePath, options) {
-    const sidebarsConfig = loadSidebarFile(sidebarFilePath);
+function loadSidebarsFile(sidebarFilePath) {
+    const sidebarsConfig = loadSidebarsFileUnsafe(sidebarFilePath);
     (0, validation_1.validateSidebars)(sidebarsConfig);
-    const normalizedSidebars = (0, normalization_1.normalizeSidebars)(sidebarsConfig, options);
-    return normalizedSidebars;
+    return sidebarsConfig;
 }
-exports.loadUnprocessedSidebars = loadUnprocessedSidebars;
+exports.loadSidebarsFile = loadSidebarsFile;
+function loadNormalizedSidebars(sidebarFilePath, params) {
+    return (0, normalization_1.normalizeSidebars)(loadSidebarsFile(sidebarFilePath), params);
+}
+exports.loadNormalizedSidebars = loadNormalizedSidebars;
 // Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 async function loadSidebars(sidebarFilePath, options) {
-    const unprocessedSidebars = loadUnprocessedSidebars(sidebarFilePath, options.options);
-    return (0, processor_1.processSidebars)(unprocessedSidebars, options);
+    const normalizeSidebarsParams = {
+        ...options.sidebarOptions,
+        version: options.version,
+        categoryLabelSlugger: (0, utils_1.createSlugger)(),
+    };
+    const normalizedSidebars = loadNormalizedSidebars(sidebarFilePath, normalizeSidebarsParams);
+    return (0, processor_1.processSidebars)(normalizedSidebars, options);
 }
 exports.loadSidebars = loadSidebars;

package/lib/sidebars/normalization.d.ts

@@ -4,6 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { SidebarOptions } from '../types';
-import type { NormalizedSidebars, SidebarsConfig } from './types';
-export declare function normalizeSidebars(sidebars: SidebarsConfig, options: SidebarOptions): NormalizedSidebars;
+import type { NormalizeSidebarsParams } from '../types';
+import type { NormalizedSidebarItem, NormalizedSidebars, SidebarItemConfig, SidebarsConfig } from './types';
+/**
+ * Normalizes recursively item and all its children. Ensures that at the end
+ * each item will be an object with the corresponding type.
+ */
+export declare function normalizeItem(item: SidebarItemConfig, options: NormalizeSidebarsParams): NormalizedSidebarItem[];
+export declare function normalizeSidebars(sidebars: SidebarsConfig, params: NormalizeSidebarsParams): NormalizedSidebars;

package/lib/sidebars/normalization.js

@@ -6,9 +6,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeSidebars = void 0;
-const lodash_1 = require("lodash");
+exports.normalizeSidebars = exports.normalizeItem = void 0;
 const utils_1 = require("./utils");
+const lodash_1 = require("lodash");
+const utils_2 = require("@docusaurus/utils");
+function normalizeCategoryLink(category, params) {
+    var _a, _b;
+    if (((_a = category.link) === null || _a === void 0 ? void 0 : _a.type) === 'generated-index') {
+        // default slug logic can be improved
+        const getDefaultSlug = () => `/category/${params.categoryLabelSlugger.slug(category.label)}`;
+        const slug = (_b = category.link.slug) !== null && _b !== void 0 ? _b : getDefaultSlug();
+        const permalink = (0, utils_2.normalizeUrl)([params.version.versionPath, slug]);
+        return {
+            ...category.link,
+            slug,
+            permalink,
+        };
+    }
+    return category.link;
+}
 function normalizeCategoriesShorthand(sidebar, options) {
     return Object.entries(sidebar).map(([label, items]) => ({
         type: 'category',
@@ -23,7 +39,7 @@ function normalizeCategoriesShorthand(sidebar, options) {
  * each item will be an object with the corresponding type.
  */
 function normalizeItem(item, options) {
-    var _a, _b;
+    var _a, _b, _c;
     if (typeof item === 'string') {
         return [
             {
@@ -33,26 +49,29 @@ function normalizeItem(item, options) {
         ];
     }
     if ((0, utils_1.isCategoriesShorthand)(item)) {
-        return normalizeCategoriesShorthand(item, options).flatMap((subitem) => normalizeItem(subitem, options));
+        return normalizeCategoriesShorthand(item, options).flatMap((subItem) => normalizeItem(subItem, options));
     }
-    return item.type === 'category'
-        ? [
-            {
-                ...item,
-                items: item.items.flatMap((subItem) => normalizeItem(subItem, options)),
-                collapsible: (_a = item.collapsible) !== null && _a !== void 0 ? _a : options.sidebarCollapsible,
-                collapsed: (_b = item.collapsed) !== null && _b !== void 0 ? _b : options.sidebarCollapsed,
-            },
-        ]
-        : [item];
+    if (item.type === 'category') {
+        const link = normalizeCategoryLink(item, options);
+        const normalizedCategory = {
+            ...item,
+            link,
+            items: ((_a = item.items) !== null && _a !== void 0 ? _a : []).flatMap((subItem) => normalizeItem(subItem, options)),
+            collapsible: (_b = item.collapsible) !== null && _b !== void 0 ? _b : options.sidebarCollapsible,
+            collapsed: (_c = item.collapsed) !== null && _c !== void 0 ? _c : options.sidebarCollapsed,
+        };
+        return [normalizedCategory];
+    }
+    return [item];
 }
+exports.normalizeItem = normalizeItem;
 function normalizeSidebar(sidebar, options) {
     const normalizedSidebar = Array.isArray(sidebar)
         ? sidebar
         : normalizeCategoriesShorthand(sidebar, options);
-    return normalizedSidebar.flatMap((subitem) => normalizeItem(subitem, options));
+    return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem, options));
 }
-function normalizeSidebars(sidebars, options) {
-    return (0, lodash_1.mapValues)(sidebars, (subitem) => normalizeSidebar(subitem, options));
+function normalizeSidebars(sidebars, params) {
+    return (0, lodash_1.mapValues)(sidebars, (items) => normalizeSidebar(items, params));
 }
 exports.normalizeSidebars = normalizeSidebars;

package/lib/sidebars/processor.d.ts

@@ -6,11 +6,13 @@
  */
 import type { NumberPrefixParser, DocMetadataBase, VersionMetadata, SidebarOptions } from '../types';
 import type { Sidebars, NormalizedSidebars, SidebarItemsGeneratorOption } from './types';
-export declare type SidebarProcessorProps = {
+import { Slugger } from '@docusaurus/utils';
+export declare type SidebarProcessorParams = {
     sidebarItemsGenerator: SidebarItemsGeneratorOption;
     numberPrefixParser: NumberPrefixParser;
     docs: DocMetadataBase[];
     version: VersionMetadata;
-    options: SidebarOptions;
+    categoryLabelSlugger: Slugger;
+    sidebarOptions: SidebarOptions;
 };
-export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, props: SidebarProcessorProps): Promise<Sidebars>;
+export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, params: SidebarProcessorParams): Promise<Sidebars>;

package/lib/sidebars/processor.js

@@ -12,9 +12,11 @@ const utils_1 = require("./utils");
 const generator_1 = require("./generator");
 const lodash_1 = require("lodash");
 const combine_promises_1 = (0, tslib_1.__importDefault)(require("combine-promises"));
+const normalization_1 = require("./normalization");
 function toSidebarItemsGeneratorDoc(doc) {
     return (0, lodash_1.pick)(doc, [
         'id',
+        'unversionedId',
         'frontMatter',
         'source',
         'sourceDirName',
@@ -25,33 +27,46 @@ function toSidebarItemsGeneratorVersion(version) {
     return (0, lodash_1.pick)(version, ['versionName', 'contentPath']);
 }
 // Handle the generation of autogenerated sidebar items and other post-processing checks
-async function processSidebar(unprocessedSidebar, { sidebarItemsGenerator, numberPrefixParser, docs, version, options, }) {
+async function processSidebar(unprocessedSidebar, params) {
+    const { sidebarItemsGenerator, numberPrefixParser, docs, version, sidebarOptions, } = params;
     // Just a minor lazy transformation optimization
     const getSidebarItemsGeneratorDocsAndVersion = (0, lodash_1.memoize)(() => ({
         docs: docs.map(toSidebarItemsGeneratorDoc),
         version: toSidebarItemsGeneratorVersion(version),
     }));
-    async function handleAutoGeneratedItems(item) {
+    async function processCategoryItem(item) {
+        return {
+            ...item,
+            items: (await Promise.all(item.items.map(processItem))).flat(),
+        };
+    }
+    async function processAutoGeneratedItem(item) {
+        // TODO the returned type can't be trusted in practice (generator can be user-provided)
+        const generatedItems = await sidebarItemsGenerator({
+            item,
+            numberPrefixParser,
+            defaultSidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
+            ...getSidebarItemsGeneratorDocsAndVersion(),
+            options: sidebarOptions,
+        });
+        // TODO validate generated items: user can generate bad items
+        const generatedItemsNormalized = generatedItems.flatMap((generatedItem) => (0, normalization_1.normalizeItem)(generatedItem, { ...params, ...sidebarOptions }));
+        // Process again... weird but sidebar item generated might generate some auto-generated items?
+        return processItems(generatedItemsNormalized);
+    }
+    async function processItem(item) {
         if (item.type === 'category') {
-            return [
-                {
-                    ...item,
-                    items: (await Promise.all(item.items.map(handleAutoGeneratedItems))).flat(),
-                },
-            ];
+            return [await processCategoryItem(item)];
         }
         if (item.type === 'autogenerated') {
-            return sidebarItemsGenerator({
-                item,
-                numberPrefixParser,
-                defaultSidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
-                ...getSidebarItemsGeneratorDocsAndVersion(),
-                options,
-            });
+            return processAutoGeneratedItem(item);
         }
         return [item];
     }
-    const processedSidebar = (await Promise.all(unprocessedSidebar.map(handleAutoGeneratedItems))).flat();
+    async function processItems(items) {
+        return (await Promise.all(items.map(processItem))).flat();
+    }
+    const processedSidebar = await processItems(unprocessedSidebar);
     const fixSidebarItemInconsistencies = (item) => {
         // A non-collapsible category can't be collapsed!
         if (item.type === 'category' && !item.collapsible && item.collapsed) {
@@ -64,7 +79,7 @@ async function processSidebar(unprocessedSidebar, { sidebarItemsGenerator, numbe
     };
     return (0, utils_1.transformSidebarItems)(processedSidebar, fixSidebarItemInconsistencies);
 }
-async function processSidebars(unprocessedSidebars, props) {
-    return (0, combine_promises_1.default)((0, lodash_1.mapValues)(unprocessedSidebars, (unprocessedSidebar) => processSidebar(unprocessedSidebar, props)));
+async function processSidebars(unprocessedSidebars, params) {
+    return (0, combine_promises_1.default)((0, lodash_1.mapValues)(unprocessedSidebars, (unprocessedSidebar) => processSidebar(unprocessedSidebar, params)));
 }
 exports.processSidebars = processSidebars;

package/lib/sidebars/types.d.ts

@@ -6,6 +6,7 @@
  */
 import type { Optional } from 'utility-types';
 import type { DocMetadataBase, VersionMetadata, NumberPrefixParser, SidebarOptions } from '../types';
+import { Required } from 'utility-types';
 declare type Expand<T extends Record<string, unknown>> = {
     [P in keyof T]: T[P];
 };
@@ -33,8 +34,28 @@ declare type SidebarItemCategoryBase = SidebarItemBase & {
     collapsed: boolean;
     collapsible: boolean;
 };
+export declare type SidebarItemCategoryLinkDoc = {
+    type: 'doc';
+    id: string;
+};
+export declare type SidebarItemCategoryLinkGeneratedIndexConfig = {
+    type: 'generated-index';
+    slug?: string;
+    title?: string;
+    description?: string;
+};
+export declare type SidebarItemCategoryLinkGeneratedIndex = {
+    type: 'generated-index';
+    slug: string;
+    permalink: string;
+    title?: string;
+    description?: string;
+};
+export declare type SidebarItemCategoryLinkConfig = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndexConfig;
+export declare type SidebarItemCategoryLink = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
 export declare type SidebarItemCategoryConfig = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
     items: SidebarItemConfig[];
+    link?: SidebarItemCategoryLinkConfig;
 }>;
 export declare type SidebarCategoriesShorthand = {
     [sidebarCategory: string]: SidebarItemConfig[];
@@ -46,6 +67,7 @@ export declare type SidebarsConfig = {
 };
 export declare type NormalizedSidebarItemCategory = Expand<SidebarItemCategoryBase & {
     items: NormalizedSidebarItem[];
+    link?: SidebarItemCategoryLink;
 }>;
 export declare type NormalizedSidebarItem = SidebarItemDoc | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
 export declare type NormalizedSidebar = NormalizedSidebarItem[];
@@ -54,8 +76,14 @@ export declare type NormalizedSidebars = {
 };
 export declare type SidebarItemCategory = Expand<SidebarItemCategoryBase & {
     items: SidebarItem[];
+    link?: SidebarItemCategoryLink;
 }>;
+export declare type SidebarItemCategoryWithLink = Required<SidebarItemCategory, 'link'>;
+export declare type SidebarItemCategoryWithGeneratedIndex = SidebarItemCategoryWithLink & {
+    link: SidebarItemCategoryLinkGeneratedIndex;
+};
 export declare type SidebarItem = SidebarItemDoc | SidebarItemLink | SidebarItemCategory;
+export declare type SidebarNavigationItem = SidebarItemDoc | SidebarItemCategoryWithLink;
 export declare type Sidebar = SidebarItem[];
 export declare type SidebarItemType = SidebarItem['type'];
 export declare type Sidebars = {
@@ -63,13 +91,26 @@ export declare type Sidebars = {
 };
 export declare type PropSidebarItemCategory = Expand<SidebarItemCategoryBase & {
     items: PropSidebarItem[];
+    href?: string;
 }>;
-export declare type PropSidebarItem = SidebarItemLink | PropSidebarItemCategory;
+export declare type PropSidebarItemLink = SidebarItemLink & {
+    docId?: string;
+};
+export declare type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
 export declare type PropSidebar = PropSidebarItem[];
 export declare type PropSidebars = {
     [sidebarId: string]: PropSidebar;
 };
-export declare type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
+export declare type PropVersionDoc = {
+    id: string;
+    title: string;
+    description?: string;
+    sidebar?: string;
+};
+export declare type PropVersionDocs = {
+    [docId: string]: PropVersionDoc;
+};
+export declare type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'unversionedId' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
 export declare type SidebarItemsGeneratorVersion = Pick<VersionMetadata, 'versionName' | 'contentPath'>;
 export declare type SidebarItemsGeneratorArgs = {
     item: SidebarItemAutogenerated;

package/lib/sidebars/utils.d.ts

@@ -5,19 +5,31 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { Sidebars, Sidebar, SidebarItem, SidebarItemCategory, SidebarItemLink, SidebarItemDoc, SidebarCategoriesShorthand, SidebarItemConfig } from './types';
+import { DocMetadataBase, DocNavLink } from '../types';
+import { SidebarItemCategoryWithGeneratedIndex, SidebarNavigationItem } from './types';
 export declare function isCategoriesShorthand(item: SidebarItemConfig): item is SidebarCategoriesShorthand;
 export declare function transformSidebarItems(sidebar: Sidebar, updateFn: (item: SidebarItem) => SidebarItem): Sidebar;
 export declare function collectSidebarDocItems(sidebar: Sidebar): SidebarItemDoc[];
 export declare function collectSidebarCategories(sidebar: Sidebar): SidebarItemCategory[];
 export declare function collectSidebarLinks(sidebar: Sidebar): SidebarItemLink[];
+export declare function collectSidebarDocIds(sidebar: Sidebar): string[];
+export declare function collectSidebarNavigation(sidebar: Sidebar): SidebarNavigationItem[];
 export declare function collectSidebarsDocIds(sidebars: Sidebars): Record<string, string[]>;
-export declare function createSidebarsUtils(sidebars: Sidebars): {
+export declare function collectSidebarsNavigations(sidebars: Sidebars): Record<string, SidebarNavigationItem[]>;
+export declare type SidebarNavigation = {
+    sidebarName: string | undefined;
+    previous: SidebarNavigationItem | undefined;
+    next: SidebarNavigationItem | undefined;
+};
+export declare type SidebarsUtils = {
+    sidebars: Sidebars;
     getFirstDocIdOfFirstSidebar: () => string | undefined;
     getSidebarNameByDocId: (docId: string) => string | undefined;
-    getDocNavigation: (docId: string) => {
-        sidebarName: string | undefined;
-        previousId: string | undefined;
-        nextId: string | undefined;
-    };
+    getDocNavigation: (unversionedId: string, versionedId: string) => SidebarNavigation;
+    getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
+    getCategoryGeneratedIndexNavigation: (categoryGeneratedIndexPermalink: string) => SidebarNavigation;
     checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
 };
+export declare function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils;
+export declare function toDocNavigationLink(doc: DocMetadataBase): DocNavLink;
+export declare function toNavigationLink(navigationItem: SidebarNavigationItem | undefined, docsById: Record<string, DocMetadataBase>): DocNavLink | undefined;