@docusaurus/plugin-content-docs 2.0.0-beta.1ec2c95e3 → 2.0.0-beta.21

package/lib/sidebars/utils.js

@@ -0,0 +1,255 @@
+"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 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;
+// /!\ 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,142 @@
+"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(),
+});
+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;

package/lib/slug.js

@@ -8,33 +8,43 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("@docusaurus/utils");
 const numberPrefix_1 = require("./numberPrefix");
-function getSlug({ baseID, frontmatterSlug, dirName, stripDirNumberPrefixes = true, numberPrefixParser = numberPrefix_1.DefaultNumberPrefixParser, }) {
-    const baseSlug = frontmatterSlug || baseID;
-    let slug;
-    if (baseSlug.startsWith('/')) {
-        slug = baseSlug;
-    }
-    else {
+const docs_1 = require("./docs");
+function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumberPrefixes = true, numberPrefixParser = numberPrefix_1.DefaultNumberPrefixParser, }) {
+    function getDirNameSlug() {
         const dirNameStripped = stripDirNumberPrefixes
-            ? numberPrefix_1.stripPathNumberPrefixes(dirName, numberPrefixParser)
-            : dirName;
-        const resolveDirname = dirName === '.'
+            ? (0, numberPrefix_1.stripPathNumberPrefixes)(sourceDirName, numberPrefixParser)
+            : sourceDirName;
+        const resolveDirname = sourceDirName === '.'
             ? '/'
-            : utils_1.addLeadingSlash(utils_1.addTrailingSlash(dirNameStripped));
-        slug = utils_1.resolvePathname(baseSlug, resolveDirname);
+            : (0, utils_1.addLeadingSlash)((0, utils_1.addTrailingSlash)(dirNameStripped));
+        return resolveDirname;
+    }
+    function computeSlug() {
+        if (frontMatterSlug?.startsWith('/')) {
+            return frontMatterSlug;
+        }
+        const dirNameSlug = getDirNameSlug();
+        if (!frontMatterSlug &&
+            (0, docs_1.isCategoryIndex)((0, docs_1.toCategoryIndexMatcherParam)({ source, sourceDirName }))) {
+            return dirNameSlug;
+        }
+        const baseSlug = frontMatterSlug ?? baseID;
+        return (0, utils_1.resolvePathname)(baseSlug, getDirNameSlug());
     }
-    if (!utils_1.isValidPathname(slug)) {
-        throw new Error(`We couldn't compute a valid slug for document with id "${baseID}" in "${dirName}" directory.
+    function ensureValidSlug(slug) {
+        if (!(0, utils_1.isValidPathname)(slug)) {
+            throw new Error(`We couldn't compute a valid slug for document with ID "${baseID}" in "${sourceDirName}" directory.
 The slug we computed looks invalid: ${slug}.
-Maybe your slug frontmatter is incorrect or you use weird chars in the file path?
-By using the slug frontmatter, you should be able to fix this error, by using the slug of your choice:
+Maybe your slug front matter is incorrect or there are special characters in the file path?
+By using front matter to set a custom slug, you should be able to fix this error:
 
-Example =>
 ---
 slug: /my/customDocPath
 ---
 `);
+        }
+        return slug;
     }
-    return slug;
+    return ensureValidSlug(computeSlug());
 }
 exports.default = getSlug;

package/{src/__tests__/__fixtures__/sidebars/sidebars-first-level-not-category.js → lib/tags.d.ts}

@@ -4,17 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
-module.exports = {
-  docs: [
-    {
-      type: 'category',
-      label: 'Getting Started',
-      items: ['greeting'],
-    },
-    {
-      type: 'doc',
-      id: 'api',
-    },
-  ],
-};
+import type { VersionTags } from './types';
+import type { DocMetadata } from '@docusaurus/plugin-content-docs';
+export declare function getVersionTags(docs: DocMetadata[]): VersionTags;

package/lib/tags.js

@@ -0,0 +1,21 @@
+"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.getVersionTags = void 0;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("@docusaurus/utils");
+function getVersionTags(docs) {
+    const groups = (0, utils_1.groupTaggedItems)(docs, (doc) => doc.tags);
+    return lodash_1.default.mapValues(groups, (group) => ({
+        label: group.tag.label,
+        docIds: group.items.map((item) => item.id),
+        permalink: group.tag.permalink,
+    }));
+}
+exports.getVersionTags = getVersionTags;

package/lib/translations.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { LoadedContent } from './types';
-import { TranslationFile, TranslationFiles } from '@docusaurus/types';
-export declare function getLoadedContentTranslationFiles(loadedContent: LoadedContent): TranslationFiles;
+import type { LoadedContent } from '@docusaurus/plugin-content-docs';
+import type { TranslationFile } from '@docusaurus/types';
+export declare function getLoadedContentTranslationFiles(loadedContent: LoadedContent): TranslationFile[];
 export declare function translateLoadedContent(loadedContent: LoadedContent, translationFiles: TranslationFile[]): LoadedContent;