@docusaurus/plugin-content-docs 2.0.0-beta.ff31de0ff → 2.0.1

package/lib/sidebars/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * 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;
+    /**
+     * This is an internal marker. Items with labels defined in the config needs
+     * to be translated with JSON
+     */
+    translatable?: true;
+};
+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 = Omit<SidebarItemDoc, 'translatable'> | 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) => NormalizedSidebar | 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) => NormalizedSidebar | Promise<NormalizedSidebar>;
+export declare type SidebarProcessorParams = {
+    sidebarItemsGenerator: SidebarItemsGeneratorOption;
+    numberPrefixParser: NumberPrefixParser;
+    docs: DocMetadataBase[];
+    drafts: DocMetadataBase[];
+    version: VersionMetadata;
+    categoryLabelSlugger: Slugger;
+    sidebarOptions: SidebarOptions;
+};
+export {};

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

@@ -1,13 +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.
  */
-
-declare module 'remark-admonitions' {
-  type Options = Record<string, unknown>;
-
-  const plugin: (options?: Options) => void;
-  export = plugin;
-}
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/sidebars/utils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 collectSidebarRefs(sidebar: Sidebar): SidebarItemDoc[];
+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;

package/lib/sidebars/utils.js

@@ -0,0 +1,259 @@
+"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.toNavigationLink = exports.toDocNavigationLink = exports.createSidebarsUtils = exports.collectSidebarsNavigations = exports.collectSidebarsDocIds = exports.collectSidebarNavigation = exports.collectSidebarDocIds = exports.collectSidebarRefs = exports.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.transformSidebarItems = exports.isCategoriesShorthand = void 0;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("@docusaurus/utils");
+function isCategoriesShorthand(item) {
+    return typeof item === 'object' && !item.type;
+}
+exports.isCategoriesShorthand = isCategoriesShorthand;
+function transformSidebarItems(sidebar, updateFn) {
+    function transformRecursive(item) {
+        if (item.type === 'category') {
+            return updateFn({
+                ...item,
+                items: item.items.map(transformRecursive),
+            });
+        }
+        return updateFn(item);
+    }
+    return sidebar.map(transformRecursive);
+}
+exports.transformSidebarItems = transformSidebarItems;
+/**
+ * Flatten sidebar items into a single flat array (containing categories/docs on
+ * the same level). Order matters (useful for next/prev nav), top categories
+ * appear before their child elements
+ */
+function flattenSidebarItems(items) {
+    function flattenRecursive(item) {
+        return item.type === 'category'
+            ? [item, ...item.items.flatMap(flattenRecursive)]
+            : [item];
+    }
+    return items.flatMap(flattenRecursive);
+}
+function collectSidebarItemsOfType(type, sidebar) {
+    return flattenSidebarItems(sidebar).filter((item) => item.type === type);
+}
+function collectSidebarDocItems(sidebar) {
+    return collectSidebarItemsOfType('doc', sidebar);
+}
+exports.collectSidebarDocItems = collectSidebarDocItems;
+function collectSidebarCategories(sidebar) {
+    return collectSidebarItemsOfType('category', sidebar);
+}
+exports.collectSidebarCategories = collectSidebarCategories;
+function collectSidebarLinks(sidebar) {
+    return collectSidebarItemsOfType('link', sidebar);
+}
+exports.collectSidebarLinks = collectSidebarLinks;
+function collectSidebarRefs(sidebar) {
+    return collectSidebarItemsOfType('ref', sidebar);
+}
+exports.collectSidebarRefs = collectSidebarRefs;
+// /!\ docId order matters for navigation!
+function collectSidebarDocIds(sidebar) {
+    return flattenSidebarItems(sidebar).flatMap((item) => {
+        if (item.type === 'category') {
+            return item.link?.type === 'doc' ? [item.link.id] : [];
+        }
+        if (item.type === 'doc') {
+            return [item.id];
+        }
+        return [];
+    });
+}
+exports.collectSidebarDocIds = collectSidebarDocIds;
+function collectSidebarNavigation(sidebar) {
+    return flattenSidebarItems(sidebar).flatMap((item) => {
+        if (item.type === 'category' && item.link) {
+            return [item];
+        }
+        if (item.type === 'doc') {
+            return [item];
+        }
+        return [];
+    });
+}
+exports.collectSidebarNavigation = collectSidebarNavigation;
+function collectSidebarsDocIds(sidebars) {
+    return lodash_1.default.mapValues(sidebars, collectSidebarDocIds);
+}
+exports.collectSidebarsDocIds = collectSidebarsDocIds;
+function collectSidebarsNavigations(sidebars) {
+    return lodash_1.default.mapValues(sidebars, collectSidebarNavigation);
+}
+exports.collectSidebarsNavigations = collectSidebarsNavigations;
+function createSidebarsUtils(sidebars) {
+    const sidebarNameToDocIds = collectSidebarsDocIds(sidebars);
+    const sidebarNameToNavigationItems = collectSidebarsNavigations(sidebars);
+    // Reverse mapping
+    const docIdToSidebarName = Object.fromEntries(Object.entries(sidebarNameToDocIds).flatMap(([sidebarName, docIds]) => docIds.map((docId) => [docId, sidebarName])));
+    function getFirstDocIdOfFirstSidebar() {
+        return Object.values(sidebarNameToDocIds)[0]?.[0];
+    }
+    function getSidebarNameByDocId(docId) {
+        return docIdToSidebarName[docId];
+    }
+    function emptySidebarNavigation() {
+        return {
+            sidebarName: undefined,
+            previous: undefined,
+            next: undefined,
+        };
+    }
+    function getDocNavigation(unversionedId, versionedId, displayedSidebar) {
+        // TODO legacy id retro-compatibility!
+        let docId = unversionedId;
+        let sidebarName = displayedSidebar === undefined
+            ? getSidebarNameByDocId(docId)
+            : displayedSidebar;
+        if (sidebarName === undefined) {
+            docId = versionedId;
+            sidebarName = getSidebarNameByDocId(docId);
+        }
+        if (!sidebarName) {
+            return emptySidebarNavigation();
+        }
+        const navigationItems = sidebarNameToNavigationItems[sidebarName];
+        if (!navigationItems) {
+            throw new Error(`Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`);
+        }
+        const currentItemIndex = navigationItems.findIndex((item) => {
+            if (item.type === 'doc') {
+                return item.id === docId;
+            }
+            if (item.type === 'category' && item.link.type === 'doc') {
+                return item.link.id === docId;
+            }
+            return false;
+        });
+        if (currentItemIndex === -1) {
+            return { sidebarName, next: undefined, previous: undefined };
+        }
+        return {
+            sidebarName,
+            previous: navigationItems[currentItemIndex - 1],
+            next: navigationItems[currentItemIndex + 1],
+        };
+    }
+    function getCategoryGeneratedIndexList() {
+        return Object.values(sidebarNameToNavigationItems)
+            .flat()
+            .flatMap((item) => {
+            if (item.type === 'category' && item.link.type === 'generated-index') {
+                return [item];
+            }
+            return [];
+        });
+    }
+    /**
+     * We identity the category generated index by its permalink (should be
+     * unique). More reliable than using object identity
+     */
+    function getCategoryGeneratedIndexNavigation(categoryGeneratedIndexPermalink) {
+        function isCurrentCategoryGeneratedIndexItem(item) {
+            return (item.type === 'category' &&
+                item.link.type === 'generated-index' &&
+                item.link.permalink === categoryGeneratedIndexPermalink);
+        }
+        const sidebarName = Object.entries(sidebarNameToNavigationItems).find(([, navigationItems]) => navigationItems.find(isCurrentCategoryGeneratedIndexItem))[0];
+        const navigationItems = sidebarNameToNavigationItems[sidebarName];
+        const currentItemIndex = navigationItems.findIndex(isCurrentCategoryGeneratedIndexItem);
+        return {
+            sidebarName,
+            previous: navigationItems[currentItemIndex - 1],
+            next: navigationItems[currentItemIndex + 1],
+        };
+    }
+    function checkSidebarsDocIds(validDocIds, sidebarFilePath) {
+        const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
+        const invalidSidebarDocIds = lodash_1.default.difference(allSidebarDocIds, validDocIds);
+        if (invalidSidebarDocIds.length > 0) {
+            throw new Error(`Invalid sidebar file at "${(0, utils_1.toMessageRelativeFilePath)(sidebarFilePath)}".
+These sidebar document ids do not exist:
+- ${invalidSidebarDocIds.sort().join('\n- ')}
+
+Available document ids are:
+- ${lodash_1.default.uniq(validDocIds).sort().join('\n- ')}`);
+        }
+    }
+    function getFirstLink(sidebar) {
+        for (const item of sidebar) {
+            if (item.type === 'doc') {
+                return {
+                    type: 'doc',
+                    id: item.id,
+                    label: item.label ?? item.id,
+                };
+            }
+            else if (item.type === 'category') {
+                if (item.link?.type === 'doc') {
+                    return {
+                        type: 'doc',
+                        id: item.link.id,
+                        label: item.label,
+                    };
+                }
+                else if (item.link?.type === 'generated-index') {
+                    return {
+                        type: 'generated-index',
+                        permalink: item.link.permalink,
+                        label: item.label,
+                    };
+                }
+                const firstSubItem = getFirstLink(item.items);
+                if (firstSubItem) {
+                    return firstSubItem;
+                }
+            }
+        }
+        return undefined;
+    }
+    return {
+        sidebars,
+        getFirstDocIdOfFirstSidebar,
+        getSidebarNameByDocId,
+        getDocNavigation,
+        getCategoryGeneratedIndexList,
+        getCategoryGeneratedIndexNavigation,
+        checkSidebarsDocIds,
+        getFirstLink: (id) => getFirstLink(sidebars[id]),
+    };
+}
+exports.createSidebarsUtils = createSidebarsUtils;
+function toDocNavigationLink(doc) {
+    const { title, permalink, frontMatter: { pagination_label: paginationLabel, sidebar_label: sidebarLabel, }, } = doc;
+    return { title: paginationLabel ?? sidebarLabel ?? title, permalink };
+}
+exports.toDocNavigationLink = toDocNavigationLink;
+function toNavigationLink(navigationItem, docsById) {
+    function getDocById(docId) {
+        const doc = docsById[docId];
+        if (!doc) {
+            throw new Error(`Can't create navigation link: no doc found with id=${docId}`);
+        }
+        return doc;
+    }
+    if (!navigationItem) {
+        return undefined;
+    }
+    if (navigationItem.type === 'category') {
+        return navigationItem.link.type === 'doc'
+            ? toDocNavigationLink(getDocById(navigationItem.link.id))
+            : {
+                title: navigationItem.label,
+                permalink: navigationItem.link.permalink,
+            };
+    }
+    return toDocNavigationLink(getDocById(navigationItem.id));
+}
+exports.toNavigationLink = toNavigationLink;

package/lib/sidebars/validation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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, CategoryMetadataFile } from './types';
+export declare function validateSidebars(sidebars: {
+    [sidebarId: string]: unknown;
+}): asserts sidebars is NormalizedSidebars;
+export declare function validateCategoryMetadataFile(unsafeContent: unknown): CategoryMetadataFile;

package/lib/sidebars/validation.js

@@ -0,0 +1,143 @@
+"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.validateCategoryMetadataFile = exports.validateSidebars = void 0;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+// NOTE: we don't add any default values during validation on purpose!
+// Config types are exposed to users for typechecking and we use the same type
+// in normalization
+const sidebarItemBaseSchema = utils_validation_1.Joi.object({
+    className: utils_validation_1.Joi.string(),
+    customProps: utils_validation_1.Joi.object().unknown(),
+});
+const sidebarItemAutogeneratedSchema = sidebarItemBaseSchema.append({
+    type: 'autogenerated',
+    dirName: utils_validation_1.Joi.string()
+        .required()
+        .pattern(/^[^/](?:.*[^/])?$/)
+        .message('"dirName" must be a dir path relative to the docs folder root, and should not start or end with slash'),
+});
+const sidebarItemDocSchema = sidebarItemBaseSchema.append({
+    type: utils_validation_1.Joi.string().valid('doc', 'ref').required(),
+    id: utils_validation_1.Joi.string().required(),
+    label: utils_validation_1.Joi.string(),
+    translatable: utils_validation_1.Joi.boolean(),
+});
+const sidebarItemHtmlSchema = sidebarItemBaseSchema.append({
+    type: 'html',
+    value: utils_validation_1.Joi.string().required(),
+    defaultStyle: utils_validation_1.Joi.boolean(),
+});
+const sidebarItemLinkSchema = sidebarItemBaseSchema.append({
+    type: 'link',
+    href: utils_validation_1.URISchema.required(),
+    label: utils_validation_1.Joi.string()
+        .required()
+        .messages({ 'any.unknown': '"label" must be a string' }),
+});
+const sidebarItemCategoryLinkSchema = utils_validation_1.Joi.object()
+    .allow(null)
+    .when('.type', {
+    switch: [
+        {
+            is: 'doc',
+            then: utils_validation_1.Joi.object({
+                type: 'doc',
+                id: utils_validation_1.Joi.string().required(),
+            }),
+        },
+        {
+            is: 'generated-index',
+            then: utils_validation_1.Joi.object({
+                type: 'generated-index',
+                slug: utils_validation_1.Joi.string().optional(),
+                // This one is not in the user config, only in the normalized version
+                // permalink: Joi.string().optional(),
+                title: utils_validation_1.Joi.string().optional(),
+                description: utils_validation_1.Joi.string().optional(),
+                image: utils_validation_1.Joi.string().optional(),
+                keywords: [utils_validation_1.Joi.string(), utils_validation_1.Joi.array().items(utils_validation_1.Joi.string())],
+            }),
+        },
+        {
+            is: utils_validation_1.Joi.required(),
+            then: utils_validation_1.Joi.forbidden().messages({
+                'any.unknown': 'Unknown sidebar category link type "{.type}".',
+            }),
+        },
+    ],
+});
+const sidebarItemCategorySchema = sidebarItemBaseSchema.append({
+    type: 'category',
+    label: utils_validation_1.Joi.string()
+        .required()
+        .messages({ 'any.unknown': '"label" must be a string' }),
+    items: utils_validation_1.Joi.array()
+        .required()
+        .messages({ 'any.unknown': '"items" must be an array' }),
+    // TODO: Joi doesn't allow mutual recursion. See https://github.com/sideway/joi/issues/2611
+    // .items(Joi.link('#sidebarItemSchema')),
+    link: sidebarItemCategoryLinkSchema,
+    collapsed: utils_validation_1.Joi.boolean().messages({
+        'any.unknown': '"collapsed" must be a boolean',
+    }),
+    collapsible: utils_validation_1.Joi.boolean().messages({
+        'any.unknown': '"collapsible" must be a boolean',
+    }),
+});
+const sidebarItemSchema = utils_validation_1.Joi.object().when('.type', {
+    switch: [
+        { is: 'link', then: sidebarItemLinkSchema },
+        {
+            is: utils_validation_1.Joi.string().valid('doc', 'ref').required(),
+            then: sidebarItemDocSchema,
+        },
+        { is: 'html', then: sidebarItemHtmlSchema },
+        { is: 'autogenerated', then: sidebarItemAutogeneratedSchema },
+        { is: 'category', then: sidebarItemCategorySchema },
+        {
+            is: utils_validation_1.Joi.any().required(),
+            then: utils_validation_1.Joi.forbidden().messages({
+                'any.unknown': 'Unknown sidebar item type "{.type}".',
+            }),
+        },
+    ],
+});
+// .id('sidebarItemSchema');
+function validateSidebarItem(item) {
+    // TODO: remove once with proper Joi support
+    // Because we can't use Joi to validate nested items (see above), we do it
+    // manually
+    utils_validation_1.Joi.assert(item, sidebarItemSchema);
+    if (item.type === 'category') {
+        item.items.forEach(validateSidebarItem);
+    }
+}
+function validateSidebars(sidebars) {
+    Object.values(sidebars).forEach((sidebar) => {
+        sidebar.forEach(validateSidebarItem);
+    });
+}
+exports.validateSidebars = validateSidebars;
+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(),
+    link: sidebarItemCategoryLinkSchema,
+    customProps: utils_validation_1.Joi.object().unknown(),
+});
+function validateCategoryMetadataFile(unsafeContent) {
+    const { error, value } = categoryMetadataFileSchema.validate(unsafeContent);
+    if (error) {
+        throw error;
+    }
+    return value;
+}
+exports.validateCategoryMetadataFile = validateCategoryMetadataFile;

package/lib/slug.d.ts

@@ -4,11 +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 { NumberPrefixParser } from './types';
-export default function getSlug({ baseID, frontmatterSlug, dirName, stripDirNumberPrefixes, numberPrefixParser, }: {
+import type { NumberPrefixParser, DocMetadataBase } from '@docusaurus/plugin-content-docs';
+export default function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumberPrefixes, numberPrefixParser, }: {
     baseID: string;
-    frontmatterSlug?: string;
-    dirName: string;
+    frontMatterSlug?: string;
+    source: DocMetadataBase['source'];
+    sourceDirName: DocMetadataBase['sourceDirName'];
     stripDirNumberPrefixes?: boolean;
     numberPrefixParser?: NumberPrefixParser;
 }): string;