@docusaurus/plugin-content-docs 2.0.0-beta.2 → 2.0.0-beta.20

package/lib/sidebars/index.js

@@ -0,0 +1,92 @@
+"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.loadSidebars = exports.loadSidebarsFileUnsafe = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = void 0;
+const tslib_1 = require("tslib");
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const import_fresh_1 = tslib_1.__importDefault(require("import-fresh"));
+const validation_1 = require("./validation");
+const normalization_1 = require("./normalization");
+const processor_1 = require("./processor");
+const postProcessor_1 = require("./postProcessor");
+const path_1 = tslib_1.__importDefault(require("path"));
+const utils_1 = require("@docusaurus/utils");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const js_yaml_1 = tslib_1.__importDefault(require("js-yaml"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
+exports.DefaultSidebars = {
+    defaultSidebar: [
+        {
+            type: 'autogenerated',
+            dirName: '.',
+        },
+    ],
+};
+exports.DisabledSidebars = {};
+// If a path is provided, make it absolute
+function resolveSidebarPathOption(siteDir, sidebarPathOption) {
+    return sidebarPathOption
+        ? path_1.default.resolve(siteDir, sidebarPathOption)
+        : sidebarPathOption;
+}
+exports.resolveSidebarPathOption = resolveSidebarPathOption;
+async function readCategoriesMetadata(contentPath) {
+    const categoryFiles = await (0, utils_1.Globby)('**/_category_.{json,yml,yaml}', {
+        cwd: contentPath,
+    });
+    const categoryToFile = lodash_1.default.groupBy(categoryFiles, path_1.default.dirname);
+    return (0, combine_promises_1.default)(lodash_1.default.mapValues(categoryToFile, async (files, folder) => {
+        const filePath = files[0];
+        if (files.length > 1) {
+            logger_1.default.warn `There are more than one category metadata files for path=${folder}: ${files.join(', ')}. The behavior is undetermined.`;
+        }
+        const content = await fs_extra_1.default.readFile(path_1.default.join(contentPath, filePath), 'utf-8');
+        try {
+            return (0, validation_1.validateCategoryMetadataFile)(js_yaml_1.default.load(content));
+        }
+        catch (err) {
+            logger_1.default.error `The docs sidebar category metadata file path=${filePath} looks invalid!`;
+            throw err;
+        }
+    }));
+}
+async function loadSidebarsFileUnsafe(sidebarFilePath) {
+    // false => no sidebars
+    if (sidebarFilePath === false) {
+        return exports.DisabledSidebars;
+    }
+    // undefined => defaults to autogenerated sidebars
+    if (typeof sidebarFilePath === 'undefined') {
+        return exports.DefaultSidebars;
+    }
+    // Non-existent sidebars file: no sidebars
+    // Note: this edge case can happen on versioned docs, not current version
+    // We avoid creating empty versioned sidebars file with the CLI
+    if (!(await fs_extra_1.default.pathExists(sidebarFilePath))) {
+        return exports.DisabledSidebars;
+    }
+    // We don't want sidebars to be cached because of hot reloading.
+    return (0, import_fresh_1.default)(sidebarFilePath);
+}
+exports.loadSidebarsFileUnsafe = loadSidebarsFileUnsafe;
+async function loadSidebars(sidebarFilePath, options) {
+    try {
+        const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
+        const normalizedSidebars = (0, normalization_1.normalizeSidebars)(sidebarsConfig);
+        (0, validation_1.validateSidebars)(normalizedSidebars);
+        const categoriesMetadata = await readCategoriesMetadata(options.version.contentPath);
+        const processedSidebars = await (0, processor_1.processSidebars)(normalizedSidebars, categoriesMetadata, options);
+        return (0, postProcessor_1.postProcessSidebars)(processedSidebars, options);
+    }
+    catch (err) {
+        logger_1.default.error `Sidebars file at path=${sidebarFilePath} failed to be loaded.`;
+        throw err;
+    }
+}
+exports.loadSidebars = loadSidebars;

package/lib/sidebars/normalization.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 { 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): NormalizedSidebarItem[];
+export declare function normalizeSidebars(sidebars: SidebarsConfig): NormalizedSidebars;

package/lib/sidebars/normalization.js

@@ -0,0 +1,55 @@
+"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.normalizeSidebars = exports.normalizeItem = void 0;
+const tslib_1 = require("tslib");
+const utils_1 = require("./utils");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+function normalizeCategoriesShorthand(sidebar) {
+    return Object.entries(sidebar).map(([label, items]) => ({
+        type: 'category',
+        label,
+        items,
+    }));
+}
+/**
+ * Normalizes recursively item and all its children. Ensures that at the end
+ * each item will be an object with the corresponding type.
+ */
+function normalizeItem(item) {
+    if (typeof item === 'string') {
+        return [{ type: 'doc', id: item }];
+    }
+    if ((0, utils_1.isCategoriesShorthand)(item)) {
+        // This will never throw anyways
+        return normalizeSidebar(item, 'sidebar items slice');
+    }
+    if (item.type === 'category') {
+        const normalizedCategory = {
+            ...item,
+            items: normalizeSidebar(item.items, logger_1.default.interpolate `code=${'items'} of the category name=${item.label}`),
+        };
+        return [normalizedCategory];
+    }
+    return [item];
+}
+exports.normalizeItem = normalizeItem;
+function normalizeSidebar(sidebar, place) {
+    if (!Array.isArray(sidebar) && !(0, utils_1.isCategoriesShorthand)(sidebar)) {
+        throw new Error(logger_1.default.interpolate `Invalid sidebar items collection code=${JSON.stringify(sidebar)} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See url=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`);
+    }
+    const normalizedSidebar = Array.isArray(sidebar)
+        ? sidebar
+        : normalizeCategoriesShorthand(sidebar);
+    return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem));
+}
+function normalizeSidebars(sidebars) {
+    return lodash_1.default.mapValues(sidebars, (sidebar, id) => normalizeSidebar(sidebar, logger_1.default.interpolate `sidebar name=${id}`));
+}
+exports.normalizeSidebars = normalizeSidebars;

package/lib/sidebars/postProcessor.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { Sidebars, SidebarProcessorParams, ProcessedSidebars } from './types';
+export declare function postProcessSidebars(sidebars: ProcessedSidebars, params: SidebarProcessorParams): Sidebars;

package/lib/sidebars/postProcessor.js

@@ -0,0 +1,65 @@
+"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.postProcessSidebars = void 0;
+const tslib_1 = require("tslib");
+const utils_1 = require("@docusaurus/utils");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+function normalizeCategoryLink(category, params) {
+    if (category.link?.type === 'generated-index') {
+        // Default slug logic can be improved
+        const getDefaultSlug = () => `/category/${params.categoryLabelSlugger.slug(category.label)}`;
+        const slug = category.link.slug ?? getDefaultSlug();
+        const permalink = (0, utils_1.normalizeUrl)([params.version.path, slug]);
+        return {
+            ...category.link,
+            slug,
+            permalink,
+        };
+    }
+    return category.link;
+}
+function postProcessSidebarItem(item, params) {
+    if (item.type === 'category') {
+        const category = {
+            ...item,
+            collapsed: item.collapsed ?? params.sidebarOptions.sidebarCollapsed,
+            collapsible: item.collapsible ?? params.sidebarOptions.sidebarCollapsible,
+            link: normalizeCategoryLink(item, params),
+            items: item.items.map((subItem) => postProcessSidebarItem(subItem, params)),
+        };
+        // If the current category doesn't have subitems, we render a normal link
+        // instead.
+        if (category.items.length === 0) {
+            if (!category.link) {
+                throw new Error(`Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`);
+            }
+            return category.link.type === 'doc'
+                ? {
+                    type: 'doc',
+                    label: category.label,
+                    id: category.link.id,
+                }
+                : {
+                    type: 'link',
+                    label: category.label,
+                    href: category.link.permalink,
+                };
+        }
+        // A non-collapsible category can't be collapsed!
+        if (category.collapsible === false) {
+            category.collapsed = false;
+        }
+        return category;
+    }
+    return item;
+}
+function postProcessSidebars(sidebars, params) {
+    return lodash_1.default.mapValues(sidebars, (sidebar) => sidebar.map((item) => postProcessSidebarItem(item, params)));
+}
+exports.postProcessSidebars = postProcessSidebars;

package/lib/sidebars/processor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { NormalizedSidebars, ProcessedSidebars, SidebarProcessorParams, CategoryMetadataFile } from './types';
+export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, categoriesMetadata: {
+    [filePath: string]: CategoryMetadataFile;
+}, params: SidebarProcessorParams): Promise<ProcessedSidebars>;

package/lib/sidebars/processor.js

@@ -0,0 +1,90 @@
+"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.processSidebars = void 0;
+const tslib_1 = require("tslib");
+const generator_1 = require("./generator");
+const validation_1 = require("./validation");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
+const docs_1 = require("../docs");
+function toSidebarItemsGeneratorDoc(doc) {
+    return lodash_1.default.pick(doc, [
+        'id',
+        'unversionedId',
+        'title',
+        'frontMatter',
+        'source',
+        'sourceDirName',
+        'sidebarPosition',
+    ]);
+}
+function toSidebarItemsGeneratorVersion(version) {
+    return lodash_1.default.pick(version, ['versionName', 'contentPath']);
+}
+// Handle the generation of autogenerated sidebar items and other
+// post-processing checks
+async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
+    const { sidebarItemsGenerator, numberPrefixParser, docs, drafts, version } = params;
+    // Just a minor lazy transformation optimization
+    const getSidebarItemsGeneratorDocsAndVersion = lodash_1.default.memoize(() => ({
+        docs: docs.map(toSidebarItemsGeneratorDoc),
+        version: toSidebarItemsGeneratorVersion(version),
+    }));
+    async function processAutoGeneratedItem(item) {
+        const generatedItems = await sidebarItemsGenerator({
+            item,
+            numberPrefixParser,
+            defaultSidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
+            isCategoryIndex: docs_1.isCategoryIndex,
+            ...getSidebarItemsGeneratorDocsAndVersion(),
+            categoriesMetadata,
+        });
+        // Process again... weird but sidebar item generated might generate some
+        // auto-generated items?
+        // TODO repeatedly process & unwrap autogenerated items until there are no
+        // more autogenerated items, or when loop count (e.g. 10) is reached
+        return processItems(generatedItems);
+    }
+    const draftIds = new Set(drafts.flatMap(docs_1.getDocIds));
+    const isDraftItem = (item) => {
+        if (item.type === 'doc' || item.type === 'ref') {
+            return draftIds.has(item.id);
+        }
+        // If a category only contains draft items, it should be filtered entirely.
+        if (item.type === 'category') {
+            return item.items.every(isDraftItem);
+        }
+        return false;
+    };
+    async function processItem(item) {
+        if (item.type === 'category') {
+            return [
+                {
+                    ...item,
+                    items: await processItems(item.items),
+                },
+            ];
+        }
+        if (item.type === 'autogenerated') {
+            return processAutoGeneratedItem(item);
+        }
+        return [item];
+    }
+    async function processItems(items) {
+        return (await Promise.all(items.filter((i) => !isDraftItem(i)).map(processItem))).flat();
+    }
+    const processedSidebar = await processItems(unprocessedSidebar);
+    return processedSidebar;
+}
+async function processSidebars(unprocessedSidebars, categoriesMetadata, params) {
+    const processedSidebars = await (0, combine_promises_1.default)(lodash_1.default.mapValues(unprocessedSidebars, (unprocessedSidebar) => processSidebar(unprocessedSidebar, categoriesMetadata, params)));
+    (0, validation_1.validateSidebars)(processedSidebars);
+    return processedSidebars;
+}
+exports.processSidebars = processSidebars;

package/lib/sidebars/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 { Optional, Required } from 'utility-types';
+import type { NumberPrefixParser, SidebarOptions, CategoryIndexMatcher, DocMetadataBase, VersionMetadata } from '@docusaurus/plugin-content-docs';
+import type { Slugger } from '@docusaurus/utils';
+declare type Expand<T extends {
+    [x: string]: unknown;
+}> = {
+    [P in keyof T]: T[P];
+};
+export declare type SidebarItemBase = {
+    className?: string;
+    customProps?: {
+        [key: string]: unknown;
+    };
+};
+export declare type SidebarItemDoc = SidebarItemBase & {
+    type: 'doc' | 'ref';
+    label?: string;
+    id: string;
+};
+export declare type SidebarItemHtml = SidebarItemBase & {
+    type: 'html';
+    value: string;
+    defaultStyle?: boolean;
+};
+export declare type SidebarItemLink = SidebarItemBase & {
+    type: 'link';
+    href: string;
+    label: string;
+};
+export declare type SidebarItemAutogenerated = SidebarItemBase & {
+    type: 'autogenerated';
+    dirName: string;
+};
+declare type SidebarItemCategoryBase = SidebarItemBase & {
+    type: 'category';
+    label: string;
+    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;
+    image?: string;
+    keywords?: string | readonly string[];
+};
+export declare type SidebarItemCategoryLinkGeneratedIndex = {
+    type: 'generated-index';
+    slug: string;
+    permalink: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    keywords?: string | readonly string[];
+};
+export declare type SidebarItemCategoryLinkConfig = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndexConfig;
+export declare type SidebarItemCategoryLink = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
+export declare type SidebarItemCategoryConfig = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: SidebarCategoriesShorthand | SidebarItemConfig[];
+    link?: SidebarItemCategoryLinkConfig;
+}>;
+export declare type SidebarCategoriesShorthand = {
+    [sidebarCategory: string]: SidebarCategoriesShorthand | SidebarItemConfig[];
+};
+export declare type SidebarItemConfig = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
+export declare type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
+export declare type SidebarsConfig = {
+    [sidebarId: string]: SidebarConfig;
+};
+export declare type NormalizedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: NormalizedSidebarItem[];
+    link?: SidebarItemCategoryLinkConfig;
+}>;
+export declare type NormalizedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
+export declare type NormalizedSidebar = NormalizedSidebarItem[];
+export declare type NormalizedSidebars = {
+    [sidebarId: string]: NormalizedSidebar;
+};
+export declare type ProcessedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: ProcessedSidebarItem[];
+    link?: SidebarItemCategoryLinkConfig;
+}>;
+export declare type ProcessedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | ProcessedSidebarItemCategory;
+export declare type ProcessedSidebar = ProcessedSidebarItem[];
+export declare type ProcessedSidebars = {
+    [sidebarId: string]: ProcessedSidebar;
+};
+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 | SidebarItemHtml | SidebarItemLink | SidebarItemCategory;
+export declare type SidebarNavigationItem = SidebarItemDoc | SidebarItemCategoryWithLink;
+export declare type Sidebar = SidebarItem[];
+export declare type SidebarItemType = SidebarItem['type'];
+export declare type Sidebars = {
+    [sidebarId: string]: Sidebar;
+};
+export declare type PropSidebarItemCategory = Expand<SidebarItemCategoryBase & {
+    items: PropSidebarItem[];
+    href?: string;
+}>;
+export declare type PropSidebarItemLink = SidebarItemLink & {
+    docId?: string;
+};
+export declare type PropSidebarItemHtml = SidebarItemHtml;
+export declare type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory | PropSidebarItemHtml;
+export declare type PropSidebar = PropSidebarItem[];
+export declare type PropSidebars = {
+    [sidebarId: string]: PropSidebar;
+};
+export declare type PropSidebarBreadcrumbsItem = PropSidebarItemLink | PropSidebarItemCategory;
+export declare type CategoryMetadataFile = {
+    label?: string;
+    position?: number;
+    collapsed?: boolean;
+    collapsible?: boolean;
+    className?: string;
+    link?: SidebarItemCategoryLinkConfig | null;
+    customProps?: {
+        [key: string]: unknown;
+    };
+};
+export declare type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'unversionedId' | 'title' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
+export declare type SidebarItemsGeneratorVersion = Pick<VersionMetadata, 'versionName' | 'contentPath'>;
+export declare type SidebarItemsGeneratorArgs = {
+    /** The sidebar item with type "autogenerated" to be transformed. */
+    item: SidebarItemAutogenerated;
+    /** Useful metadata for the version this sidebar belongs to. */
+    version: SidebarItemsGeneratorVersion;
+    /** All the docs of that version (unfiltered). */
+    docs: SidebarItemsGeneratorDoc[];
+    /** Number prefix parser configured for this plugin. */
+    numberPrefixParser: NumberPrefixParser;
+    /** The default category index matcher which you can override. */
+    isCategoryIndex: CategoryIndexMatcher;
+    /**
+     * Key is the path relative to the doc content directory, value is the
+     * category metadata file's content.
+     */
+    categoriesMetadata: {
+        [filePath: string]: CategoryMetadataFile;
+    };
+};
+export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => Promise<NormalizedSidebar>;
+export declare type SidebarItemsGeneratorOption = (generatorArgs: {
+    /**
+     * Useful to re-use/enhance the default sidebar generation logic from
+     * Docusaurus.
+     * @see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
+     */
+    defaultSidebarItemsGenerator: SidebarItemsGenerator;
+} & SidebarItemsGeneratorArgs) => Promise<NormalizedSidebarItem[]>;
+export declare type SidebarProcessorParams = {
+    sidebarItemsGenerator: SidebarItemsGeneratorOption;
+    numberPrefixParser: NumberPrefixParser;
+    docs: DocMetadataBase[];
+    drafts: DocMetadataBase[];
+    version: VersionMetadata;
+    categoryLabelSlugger: Slugger;
+    sidebarOptions: SidebarOptions;
+};
+export {};

package/lib/{docFrontMatter.d.ts → sidebars/types.js}

@@ -1,8 +1,8 @@
+"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.
  */
-import { DocFrontMatter } from './types';
-export declare function validateDocFrontMatter(frontMatter: Record<string, unknown>): DocFrontMatter;
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/sidebars/utils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 { Sidebars, Sidebar, SidebarItem, SidebarItemCategory, SidebarItemLink, SidebarItemDoc, SidebarCategoriesShorthand, SidebarItemConfig, SidebarItemCategoryWithGeneratedIndex, SidebarNavigationItem } from './types';
+import type { DocMetadataBase, PropNavigationLink } from '@docusaurus/plugin-content-docs';
+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): {
+    [sidebarId: string]: string[];
+};
+export declare function collectSidebarsNavigations(sidebars: Sidebars): {
+    [sidebarId: 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: (unversionedId: string, versionedId: string, displayedSidebar: string | null | undefined) => SidebarNavigation;
+    getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
+    getCategoryGeneratedIndexNavigation: (categoryGeneratedIndexPermalink: string) => SidebarNavigation;
+    /**
+     * This function may return undefined. This is usually a user mistake, because
+     * it means this sidebar will never be displayed; however, we can still use
+     * `displayed_sidebar` to make it displayed. Pretty weird but valid use-case
+     */
+    getFirstLink: (sidebarId: string) => {
+        type: 'doc';
+        id: string;
+        label: string;
+    } | {
+        type: 'generated-index';
+        permalink: string;
+        label: string;
+    } | undefined;
+    checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
+};
+export declare function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils;
+export declare function toDocNavigationLink(doc: DocMetadataBase): PropNavigationLink;
+export declare function toNavigationLink(navigationItem: SidebarNavigationItem | undefined, docsById: {
+    [docId: string]: DocMetadataBase;
+}): PropNavigationLink | undefined;