@azerion/bunosaurus-plugin-content-docs 0.0.0-stage → 4.0.0

package/lib/sidebars/utils.js

@@ -0,0 +1,327 @@
+"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.isCategoriesShorthand = isCategoriesShorthand;
+exports.transformSidebarItems = transformSidebarItems;
+exports.collectSidebarDocItems = collectSidebarDocItems;
+exports.collectSidebarCategories = collectSidebarCategories;
+exports.collectSidebarLinks = collectSidebarLinks;
+exports.collectSidebarRefs = collectSidebarRefs;
+exports.collectSidebarDocIds = collectSidebarDocIds;
+exports.collectSidebarNavigation = collectSidebarNavigation;
+exports.collectSidebarsDocIds = collectSidebarsDocIds;
+exports.collectSidebarsNavigations = collectSidebarsNavigations;
+exports.createSidebarsUtils = createSidebarsUtils;
+exports.toDocNavigationLink = toDocNavigationLink;
+exports.toNavigationLink = toNavigationLink;
+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;
+}
+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);
+}
+/**
+ * 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);
+}
+function collectSidebarCategories(sidebar) {
+    return collectSidebarItemsOfType('category', sidebar);
+}
+function collectSidebarLinks(sidebar) {
+    return collectSidebarItemsOfType('link', sidebar);
+}
+function collectSidebarRefs(sidebar) {
+    return collectSidebarItemsOfType('ref', sidebar);
+}
+// /!\ 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 [];
+    });
+}
+function collectSidebarNavigation(sidebar) {
+    return flattenSidebarItems(sidebar).flatMap((item) => {
+        if (item.type === 'category' && item.link) {
+            return [item];
+        }
+        if (item.type === 'doc') {
+            return [item];
+        }
+        return [];
+    });
+}
+function collectSidebarsDocIds(sidebars) {
+    return lodash_1.default.mapValues(sidebars, collectSidebarDocIds);
+}
+function collectSidebarsNavigations(sidebars) {
+    return lodash_1.default.mapValues(sidebars, collectSidebarNavigation);
+}
+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({ docId, displayedSidebar, unlistedIds, }) {
+        const sidebarName = displayedSidebar === undefined
+            ? getSidebarNameByDocId(docId)
+            : displayedSidebar;
+        if (!sidebarName) {
+            return emptySidebarNavigation();
+        }
+        let 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`);
+        }
+        // Filter unlisted items from navigation
+        navigationItems = navigationItems.filter((item) => {
+            if (item.type === 'doc' && unlistedIds.has(item.id)) {
+                return false;
+            }
+            if (item.type === 'category' &&
+                item.link.type === 'doc' &&
+                unlistedIds.has(item.link.id)) {
+                return false;
+            }
+            return true;
+        });
+        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],
+        };
+    }
+    // TODO remove in Docusaurus v4
+    function getLegacyVersionedPrefix(versionMetadata) {
+        return `version-${versionMetadata.versionName}/`;
+    }
+    // In early v2, sidebar names used to be versioned
+    // example: "version-2.0.0-alpha.66/my-sidebar-name"
+    // In v3 it's not the case anymore and we throw an error to explain
+    // TODO remove in Docusaurus v4
+    function checkLegacyVersionedSidebarNames({ versionMetadata, sidebarFilePath, }) {
+        const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
+        const legacySidebarNames = Object.keys(sidebars).filter((sidebarName) => sidebarName.startsWith(illegalPrefix));
+        if (legacySidebarNames.length > 0) {
+            throw new Error(`Invalid sidebar file at "${(0, utils_1.toMessageRelativeFilePath)(sidebarFilePath)}".
+These legacy versioned sidebar names are not supported anymore in Docusaurus v3:
+- ${legacySidebarNames.sort().join('\n- ')}
+
+The sidebar names you should now use are:
+- ${legacySidebarNames
+                .sort()
+                .map((legacyName) => legacyName.split('/').splice(1).join('/'))
+                .join('\n- ')}
+
+Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
+This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
+`);
+        }
+    }
+    // throw a better error message for Docusaurus v3 breaking change
+    // TODO this can be removed in Docusaurus v4
+    function handleLegacyVersionedDocIds({ invalidDocIds, sidebarFilePath, versionMetadata, }) {
+        const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
+        // In older v2.0 alpha/betas, versioned docs had a legacy versioned prefix
+        // Example: "version-1.4/my-doc-id"
+        //
+        const legacyVersionedDocIds = invalidDocIds.filter((docId) => docId.startsWith(illegalPrefix));
+        if (legacyVersionedDocIds.length > 0) {
+            throw new Error(`Invalid sidebar file at "${(0, utils_1.toMessageRelativeFilePath)(sidebarFilePath)}".
+These legacy versioned document ids are not supported anymore in Docusaurus v3:
+- ${legacyVersionedDocIds.sort().join('\n- ')}
+
+The document ids you should now use are:
+- ${legacyVersionedDocIds
+                .sort()
+                .map((legacyId) => legacyId.split('/').splice(1).join('/'))
+                .join('\n- ')}
+
+Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
+This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
+`);
+        }
+    }
+    function checkSidebarsDocIds({ allDocIds, sidebarFilePath, versionMetadata, }) {
+        const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
+        const invalidDocIds = lodash_1.default.difference(allSidebarDocIds, allDocIds);
+        if (invalidDocIds.length > 0) {
+            handleLegacyVersionedDocIds({
+                invalidDocIds,
+                sidebarFilePath,
+                versionMetadata,
+            });
+            throw new Error(`Invalid sidebar file at "${(0, utils_1.toMessageRelativeFilePath)(sidebarFilePath)}".
+These sidebar document ids do not exist:
+- ${invalidDocIds.sort().join('\n- ')}
+
+Available document ids are:
+- ${lodash_1.default.uniq(allDocIds).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,
+        checkLegacyVersionedSidebarNames,
+        checkSidebarsDocIds,
+        getFirstLink: (id) => getFirstLink(sidebars[id]),
+    };
+}
+function toDocNavigationLink(doc, options) {
+    const { title, permalink, frontMatter: { pagination_label: paginationLabel, sidebar_label: sidebarLabel, }, } = doc;
+    return {
+        title: paginationLabel ?? sidebarLabel ?? options?.sidebarItemLabel ?? title,
+        permalink,
+    };
+}
+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), {
+        sidebarItemLabel: navigationItem?.label,
+    });
+}

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,152 @@
+"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.validateSidebars = validateSidebars;
+exports.validateCategoryMetadataFile = validateCategoryMetadataFile;
+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({
+    key: utils_validation_1.Joi.string(),
+    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(),
+    autoAddBaseUrl: utils_validation_1.Joi.boolean(),
+    label: utils_validation_1.Joi.string()
+        .required()
+        .messages({ 'any.unknown': '"label" must be a string' }),
+    description: utils_validation_1.Joi.string().optional().messages({
+        'any.unknown': '"description" 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',
+    }),
+    description: utils_validation_1.Joi.string().optional().messages({
+        'any.unknown': '"description" must be a string',
+    }),
+});
+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);
+    });
+}
+const categoryMetadataFileSchema = utils_validation_1.Joi.object({
+    key: utils_validation_1.Joi.string(),
+    label: utils_validation_1.Joi.string(),
+    description: 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;
+}

package/lib/slug.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 } from '@docusaurus/plugin-content-docs';
+export default function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumberPrefixes, numberPrefixParser, }: {
+    baseID: string;
+    frontMatterSlug?: string;
+    source: DocMetadataBase['source'];
+    sourceDirName: DocMetadataBase['sourceDirName'];
+    stripDirNumberPrefixes?: boolean;
+    numberPrefixParser?: NumberPrefixParser;
+}): string;

package/lib/slug.js

@@ -0,0 +1,51 @@
+"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.default = getSlug;
+const utils_1 = require("@docusaurus/utils");
+const utils_common_1 = require("@docusaurus/utils-common");
+const numberPrefix_1 = require("./numberPrefix");
+const docs_1 = require("./docs");
+function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumberPrefixes = true, numberPrefixParser = numberPrefix_1.DefaultNumberPrefixParser, }) {
+    function getDirNameSlug() {
+        const dirNameStripped = stripDirNumberPrefixes
+            ? (0, numberPrefix_1.stripPathNumberPrefixes)(sourceDirName, numberPrefixParser)
+            : sourceDirName;
+        const resolveDirname = sourceDirName === '.'
+            ? '/'
+            : (0, utils_common_1.addLeadingSlash)((0, utils_common_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());
+    }
+    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 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:
+
+---
+slug: /my/customDocPath
+---
+`);
+        }
+        return slug;
+    }
+    return ensureValidSlug(computeSlug());
+}

package/lib/translations.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 { 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;