@docusaurus/plugin-content-docs 2.0.0-beta.138b4c997 → 2.0.0-beta.14

package/lib/sidebars/processor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { NumberPrefixParser, DocMetadataBase, VersionMetadata, SidebarOptions } from '../types';
+import type { Sidebars, NormalizedSidebars, SidebarItemsGeneratorOption } from './types';
+import { Slugger } from '@docusaurus/utils';
+export declare type SidebarProcessorParams = {
+    sidebarItemsGenerator: SidebarItemsGeneratorOption;
+    numberPrefixParser: NumberPrefixParser;
+    docs: DocMetadataBase[];
+    version: VersionMetadata;
+    categoryLabelSlugger: Slugger;
+    sidebarOptions: SidebarOptions;
+};
+export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, params: SidebarProcessorParams): Promise<Sidebars>;

package/lib/sidebars/processor.js

@@ -0,0 +1,85 @@
+"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 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',
+        'sidebarPosition',
+    ]);
+}
+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, 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 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 [await processCategoryItem(item)];
+        }
+        if (item.type === 'autogenerated') {
+            return processAutoGeneratedItem(item);
+        }
+        return [item];
+    }
+    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) {
+            return {
+                ...item,
+                collapsed: false,
+            };
+        }
+        return item;
+    };
+    return (0, utils_1.transformSidebarItems)(processedSidebar, fixSidebarItemInconsistencies);
+}
+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

@@ -0,0 +1,127 @@
+/**
+ * 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 } 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];
+};
+export declare type SidebarItemBase = {
+    className?: string;
+    customProps?: Record<string, unknown>;
+};
+export declare type SidebarItemDoc = SidebarItemBase & {
+    type: 'doc' | 'ref';
+    label?: string;
+    id: string;
+};
+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;
+};
+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[];
+};
+export declare type SidebarItemConfig = SidebarItemDoc | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
+export declare type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
+export declare type SidebarsConfig = {
+    [sidebarId: string]: SidebarConfig;
+};
+export declare type NormalizedSidebarItemCategory = Expand<SidebarItemCategoryBase & {
+    items: NormalizedSidebarItem[];
+    link?: SidebarItemCategoryLink;
+}>;
+export declare type NormalizedSidebarItem = SidebarItemDoc | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
+export declare type NormalizedSidebar = NormalizedSidebarItem[];
+export declare type NormalizedSidebars = {
+    [sidebarId: string]: NormalizedSidebar;
+};
+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 = {
+    [sidebarId: string]: Sidebar;
+};
+export declare type PropSidebarItemCategory = Expand<SidebarItemCategoryBase & {
+    items: PropSidebarItem[];
+    href?: string;
+}>;
+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 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;
+    version: SidebarItemsGeneratorVersion;
+    docs: SidebarItemsGeneratorDoc[];
+    numberPrefixParser: NumberPrefixParser;
+    options: SidebarOptions;
+};
+export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => Promise<SidebarItem[]>;
+export declare type SidebarItemsGeneratorOptionArgs = {
+    defaultSidebarItemsGenerator: SidebarItemsGenerator;
+} & SidebarItemsGeneratorArgs;
+export declare type SidebarItemsGeneratorOption = (generatorArgs: SidebarItemsGeneratorOptionArgs) => Promise<SidebarItem[]>;
+export {};

package/{src/__tests__/__fixtures__/site-with-autogenerated-sidebar/partialAutogeneratedSidebars2.js → lib/sidebars/types.js}

@@ -1,16 +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.
  */
-
-module.exports = {
-  someSidebar: [
-    {type: 'doc', id: 'API/api-end'},
-    {
-      type: 'autogenerated',
-      dirName: '3-API',
-    },
-  ],
-};
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/sidebars/utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 } 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 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: (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;

package/lib/sidebars/utils.js

@@ -0,0 +1,228 @@
+"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.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.transformSidebarItems = exports.isCategoriesShorthand = void 0;
+const lodash_1 = require("lodash");
+const utils_1 = require("@docusaurus/utils");
+function isCategoriesShorthand(item) {
+    return typeof item !== 'string' && !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;
+// /!\ docId order matters for navigation!
+function collectSidebarDocIds(sidebar) {
+    return flattenSidebarItems(sidebar).flatMap((item) => {
+        var _a;
+        if (item.type === 'category') {
+            return ((_a = item.link) === null || _a === void 0 ? void 0 : _a.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 (0, lodash_1.mapValues)(sidebars, collectSidebarDocIds);
+}
+exports.collectSidebarsDocIds = collectSidebarsDocIds;
+function collectSidebarsNavigations(sidebars) {
+    return (0, lodash_1.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() {
+        var _a;
+        return (_a = Object.values(sidebarNameToDocIds)[0]) === null || _a === void 0 ? void 0 : _a[0];
+    }
+    function getSidebarNameByDocId(docId) {
+        return docIdToSidebarName[docId];
+    }
+    function emptySidebarNavigation() {
+        return {
+            sidebarName: undefined,
+            previous: undefined,
+            next: undefined,
+        };
+    }
+    function getDocNavigation(unversionedId, versionedId) {
+        // TODO legacy id retro-compatibility!
+        let docId = unversionedId;
+        let sidebarName = getSidebarNameByDocId(docId);
+        if (!sidebarName) {
+            docId = versionedId;
+            sidebarName = getSidebarNameByDocId(docId);
+        }
+        if (sidebarName) {
+            const navigationItems = sidebarNameToNavigationItems[sidebarName];
+            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;
+            });
+            const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
+            return { sidebarName, previous, next };
+        }
+        else {
+            return emptySidebarNavigation();
+        }
+    }
+    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) {
+        var _a;
+        function isCurrentCategoryGeneratedIndexItem(item) {
+            var _a;
+            return (item.type === 'category' &&
+                ((_a = item.link) === null || _a === void 0 ? void 0 : _a.type) === 'generated-index' &&
+                item.link.permalink === categoryGeneratedIndexPermalink);
+        }
+        const sidebarName = (_a = Object.entries(sidebarNameToNavigationItems).find(([, navigationItems]) => navigationItems.find(isCurrentCategoryGeneratedIndexItem))) === null || _a === void 0 ? void 0 : _a[0];
+        if (sidebarName) {
+            const navigationItems = sidebarNameToNavigationItems[sidebarName];
+            const currentItemIndex = navigationItems.findIndex(isCurrentCategoryGeneratedIndexItem);
+            const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
+            return { sidebarName, previous, next };
+        }
+        else {
+            return emptySidebarNavigation();
+        }
+    }
+    function checkSidebarsDocIds(validDocIds, sidebarFilePath) {
+        const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
+        const invalidSidebarDocIds = (0, lodash_1.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:
+- ${(0, lodash_1.uniq)(validDocIds).sort().join('\n- ')}`);
+        }
+    }
+    return {
+        sidebars,
+        getFirstDocIdOfFirstSidebar,
+        getSidebarNameByDocId,
+        getDocNavigation,
+        getCategoryGeneratedIndexList,
+        getCategoryGeneratedIndexNavigation,
+        checkSidebarsDocIds,
+    };
+}
+exports.createSidebarsUtils = createSidebarsUtils;
+function toDocNavigationLink(doc) {
+    var _a;
+    const { title, permalink, frontMatter: { pagination_label: paginationLabel, sidebar_label: sidebarLabel, }, } = doc;
+    return { title: (_a = paginationLabel !== null && paginationLabel !== void 0 ? paginationLabel : sidebarLabel) !== null && _a !== void 0 ? _a : 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;
+    }
+    function handleCategory(category) {
+        if (category.link.type === 'doc') {
+            return toDocNavigationLink(getDocById(category.link.id));
+        }
+        else if (category.link.type === 'generated-index') {
+            return {
+                title: category.label,
+                permalink: category.link.permalink,
+            };
+        }
+        else {
+            throw new Error('unexpected category link type');
+        }
+    }
+    if (!navigationItem) {
+        return undefined;
+    }
+    if (navigationItem.type === 'doc') {
+        return toDocNavigationLink(getDocById(navigationItem.id));
+    }
+    else if (navigationItem.type === 'category') {
+        return handleCategory(navigationItem);
+    }
+    else {
+        throw new Error('unexpected navigation item');
+    }
+}
+exports.toNavigationLink = toNavigationLink;

package/lib/sidebars/validation.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 { SidebarsConfig } from './types';
+import { CategoryMetadataFile } from './generator';
+export declare function validateSidebars(sidebars: unknown): asserts sidebars is SidebarsConfig;
+export declare function validateCategoryMetadataFile(unsafeContent: unknown): CategoryMetadataFile;

package/lib/sidebars/validation.js

@@ -0,0 +1,138 @@
+"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");
+const utils_1 = require("./utils");
+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(),
+});
+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()
+    .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(),
+                // permalink: Joi.string().optional(), // No, this one is not in the user config, only in the normalized version
+                title: utils_validation_1.Joi.string().optional(),
+                description: utils_validation_1.Joi.string().optional(),
+            }),
+        },
+        {
+            is: utils_validation_1.Joi.string().required(),
+            then: utils_validation_1.Joi.forbidden().messages({
+                'any.unknown': 'Unknown sidebar category link type "{.type}".',
+            }),
+        },
+    ],
+})
+    .id('sidebarCategoryLinkSchema');
+const sidebarItemCategorySchema = sidebarItemBaseSchema.append({
+    type: 'category',
+    label: utils_validation_1.Joi.string()
+        .required()
+        .messages({ 'any.unknown': '"label" must be a string' }),
+    // TODO: Joi doesn't allow mutual recursion. See https://github.com/sideway/joi/issues/2611
+    items: utils_validation_1.Joi.array()
+        .required()
+        .messages({ 'any.unknown': '"items" must be an array' }),
+    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: '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) {
+    if (typeof item === 'string') {
+        return;
+    }
+    // TODO: remove once with proper Joi support
+    // Because we can't use Joi to validate nested items (see above), we do it manually
+    if ((0, utils_1.isCategoriesShorthand)(item)) {
+        Object.values(item).forEach((category) => category.forEach(validateSidebarItem));
+    }
+    else {
+        utils_validation_1.Joi.assert(item, sidebarItemSchema);
+        if (item.type === 'category') {
+            item.items.forEach(validateSidebarItem);
+        }
+    }
+}
+function validateSidebars(sidebars) {
+    Object.values(sidebars).forEach((sidebar) => {
+        if (Array.isArray(sidebar)) {
+            sidebar.forEach(validateSidebarItem);
+        }
+        else {
+            validateSidebarItem(sidebar);
+        }
+    });
+}
+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,
+});
+function validateCategoryMetadataFile(unsafeContent) {
+    return utils_validation_1.Joi.attempt(unsafeContent, categoryMetadataFileSchema);
+}
+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 { DocMetadataBase, NumberPrefixParser } from './types';
+export default function getSlug({ baseID, frontmatterSlug, source, sourceDirName, stripDirNumberPrefixes, numberPrefixParser, }: {
     baseID: string;
     frontmatterSlug?: string;
-    dirName: string;
+    source: DocMetadataBase['slug'];
+    sourceDirName: DocMetadataBase['sourceDirName'];
     stripDirNumberPrefixes?: boolean;
     numberPrefixParser?: NumberPrefixParser;
 }): string;