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

package/lib/index.js

@@ -0,0 +1,198 @@
+"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.validateOptions = void 0;
+exports.default = pluginContentDocs;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const utils_1 = require("@docusaurus/utils");
+const glob_1 = require("@docusaurus/glob");
+const utils_validation_1 = require("@docusaurus/utils-validation");
+const mdx_loader_1 = require("@docusaurus/mdx-loader");
+const fs_1 = require("@docusaurus/fs");
+const sidebars_1 = require("./sidebars");
+const generator_1 = require("./sidebars/generator");
+const version_1 = require("./versions/version");
+const cli_1 = tslib_1.__importDefault(require("./cli"));
+const constants_1 = require("./constants");
+const globalData_1 = require("./globalData");
+const translations_1 = require("./translations");
+const routes_1 = require("./routes");
+const contentHelpers_1 = require("./contentHelpers");
+const loadVersion_1 = require("./versions/loadVersion");
+// MDX loader is not 100% deterministic, leading to cache invalidation issue
+// This permits to invalidate the MDX loader cache entries when content changes
+// Problem documented here: https://github.com/facebook/docusaurus/pull/10934
+// TODO this is not a perfect solution, find better?
+async function createMdxLoaderDependencyFile({ dataDir, options, versionsMetadata, }) {
+    // Disabled for unit tests, the side effect produces infinite watch loops
+    // TODO find a better way :/
+    if (process.env.NODE_ENV === 'test') {
+        return undefined;
+    }
+    const filePath = node_path_1.default.join(dataDir, '__mdx-loader-dependency.json');
+    // the cache is invalidated whenever this file content changes
+    const fileContent = {
+        options,
+        versionsMetadata,
+    };
+    await fs_1.fs.mkdir(dataDir, { recursive: true });
+    await fs_1.fs.writeFile(filePath, JSON.stringify(fileContent));
+    return filePath;
+}
+async function pluginContentDocs(context, options) {
+    const { siteDir, generatedFilesDir, baseUrl, siteConfig } = context;
+    // Mutate options to resolve sidebar path according to siteDir
+    options.sidebarPath = (0, sidebars_1.resolveSidebarPathOption)(siteDir, options.sidebarPath);
+    const versionsMetadata = await (0, version_1.readVersionsMetadata)({ context, options });
+    const pluginId = options.id;
+    const pluginDataDirRoot = node_path_1.default.join(generatedFilesDir, 'docusaurus-plugin-content-docs');
+    const dataDir = node_path_1.default.join(pluginDataDirRoot, pluginId);
+    // TODO Docusaurus v4 breaking change
+    //  module aliasing should be automatic
+    //  we should never find local absolute FS paths in the codegen registry
+    const aliasedSource = (source) => `~docs/${(0, utils_1.posixPath)(node_path_1.default.relative(pluginDataDirRoot, source))}`;
+    // TODO env should be injected into all plugins
+    const env = process.env.NODE_ENV;
+    const contentHelpers = (0, contentHelpers_1.createContentHelpers)();
+    const mdxLoaderDependency = await createMdxLoaderDependencyFile({
+        dataDir,
+        options,
+        versionsMetadata,
+    });
+    function createDocsMDXLoaderRule() {
+        const { rehypePlugins, remarkPlugins, recmaPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
+        const contentDirs = versionsMetadata
+            .flatMap(utils_1.getContentPathList)
+            // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+            .map(utils_1.addTrailingPathSeparator);
+        return (0, mdx_loader_1.createMDXLoaderRule)({
+            include: contentDirs,
+            options: {
+                dependencies: [mdxLoaderDependency].filter((d) => typeof d === 'string'),
+                admonitions: options.admonitions,
+                remarkPlugins,
+                rehypePlugins,
+                recmaPlugins,
+                beforeDefaultRehypePlugins,
+                beforeDefaultRemarkPlugins,
+                staticDirs: siteConfig.staticDirectories.map((dir) => node_path_1.default.resolve(siteDir, dir)),
+                siteDir,
+                isMDXPartial: (0, glob_1.createAbsoluteFilePathMatcher)(options.exclude, contentDirs),
+                metadataPath: (mdxPath) => {
+                    // Note that metadataPath must be the same/in-sync as
+                    // the path from createData for each MDX.
+                    const aliasedPath = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
+                    return node_path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedPath)}.json`);
+                },
+                // createAssets converts relative paths to require() calls
+                createAssets: ({ frontMatter }) => ({
+                    image: frontMatter.image,
+                }),
+                markdownConfig: siteConfig.markdown,
+                resolveMarkdownLink: ({ linkPathname, sourceFilePath }) => {
+                    const version = (0, version_1.getVersionFromSourceFilePath)(sourceFilePath, versionsMetadata);
+                    return (0, utils_1.resolveMarkdownLinkPathname)(linkPathname, {
+                        sourceFilePath,
+                        sourceToPermalink: contentHelpers.sourceToPermalink,
+                        siteDir,
+                        contentPaths: version,
+                    });
+                },
+            },
+        });
+    }
+    const docsMDXLoaderRule = createDocsMDXLoaderRule();
+    return {
+        name: 'docusaurus-plugin-content-docs',
+        extendCli(cli) {
+            const isDefaultPluginId = pluginId === utils_1.DEFAULT_PLUGIN_ID;
+            // Need to create one distinct command per plugin instance
+            // otherwise 2 instances would try to execute the command!
+            const command = isDefaultPluginId
+                ? 'docs:version'
+                : `docs:version:${pluginId}`;
+            const commandDescription = isDefaultPluginId
+                ? 'Tag a new docs version'
+                : `Tag a new docs version (${pluginId})`;
+            cli
+                .command(command)
+                .arguments('<version>')
+                .description(commandDescription)
+                .action((version) => cli_1.default.cliDocsVersionCommand(version, options, context));
+        },
+        getTranslationFiles({ content }) {
+            return (0, translations_1.getLoadedContentTranslationFiles)(content);
+        },
+        getPathsToWatch() {
+            function getVersionPathsToWatch(version) {
+                const result = [
+                    ...options.include.flatMap((pattern) => (0, utils_1.getContentPathList)(version).map((docsDirPath) => `${docsDirPath}/${pattern}`)),
+                    ...(0, utils_validation_1.getTagsFilePathsToWatch)({
+                        contentPaths: version,
+                        tags: options.tags,
+                    }),
+                    `${version.contentPath}/**/${generator_1.CategoryMetadataFilenamePattern}`,
+                ];
+                if (typeof version.sidebarFilePath === 'string') {
+                    result.unshift(version.sidebarFilePath);
+                }
+                return result;
+            }
+            return versionsMetadata.flatMap(getVersionPathsToWatch);
+        },
+        async loadContent() {
+            return {
+                loadedVersions: await Promise.all(versionsMetadata.map((versionMetadata) => (0, loadVersion_1.loadVersion)({
+                    context,
+                    options,
+                    env,
+                    versionMetadata,
+                }))),
+            };
+        },
+        translateContent({ content, translationFiles }) {
+            return (0, translations_1.translateLoadedContent)(content, translationFiles);
+        },
+        async contentLoaded({ content, actions }) {
+            contentHelpers.updateContent(content);
+            const versions = content.loadedVersions.map(version_1.toFullVersion);
+            await (0, routes_1.createAllRoutes)({
+                baseUrl,
+                versions,
+                options,
+                actions,
+                aliasedSource,
+            });
+            actions.setGlobalData({
+                path: (0, utils_1.normalizeUrl)([baseUrl, options.routeBasePath]),
+                versions: versions.map(globalData_1.toGlobalDataVersion),
+                breadcrumbs: options.breadcrumbs,
+            });
+        },
+        configureWebpack() {
+            return {
+                ignoreWarnings: [
+                    // Suppress warnings about non-existing of versions file.
+                    (e) => e.message.includes("Can't resolve") &&
+                        e.message.includes(constants_1.VERSIONS_JSON_FILE),
+                ],
+                resolve: {
+                    alias: {
+                        '~docs': pluginDataDirRoot,
+                    },
+                },
+                module: {
+                    rules: [docsMDXLoaderRule],
+                },
+            };
+        },
+    };
+}
+var options_1 = require("./options");
+Object.defineProperty(exports, "validateOptions", { enumerable: true, get: function () { return options_1.validateOptions; } });

package/lib/numberPrefix.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 { NumberPrefixParser } from '@docusaurus/plugin-content-docs';
+export declare const DefaultNumberPrefixParser: NumberPrefixParser;
+export declare const DisabledNumberPrefixParser: NumberPrefixParser;
+export declare function stripNumberPrefix(str: string, parser: NumberPrefixParser): string;
+export declare function stripPathNumberPrefixes(path: string, parser: NumberPrefixParser): string;

package/lib/numberPrefix.js

@@ -0,0 +1,50 @@
+"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.DisabledNumberPrefixParser = exports.DefaultNumberPrefixParser = void 0;
+exports.stripNumberPrefix = stripNumberPrefix;
+exports.stripPathNumberPrefixes = stripPathNumberPrefixes;
+// Best-effort to avoid parsing some patterns as number prefix
+// ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
+// ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
+// Both of them would look like 7.0-foo or 2021-11-foo
+// note: we could try to parse float numbers in filenames, but that is probably
+// not worth it, as a version such as "8.0" can be interpreted as either a
+// version or a float. User can configure her own NumberPrefixParser if she
+// wants 8.0 to be interpreted as a float
+const ignoredPrefixPattern = /^\d+[-_.]\d+/;
+const numberPrefixPattern = /^(?<numberPrefix>\d+)\s*[-_.]+\s*(?<suffix>[^-_.\s].*)$/;
+// 0-myDoc => {filename: myDoc, numberPrefix: 0}
+// 003 - myDoc => {filename: myDoc, numberPrefix: 3}
+const DefaultNumberPrefixParser = (filename) => {
+    if (ignoredPrefixPattern.test(filename)) {
+        return { filename, numberPrefix: undefined };
+    }
+    const match = numberPrefixPattern.exec(filename);
+    if (!match) {
+        return { filename, numberPrefix: undefined };
+    }
+    return {
+        filename: match.groups.suffix,
+        numberPrefix: parseInt(match.groups.numberPrefix, 10),
+    };
+};
+exports.DefaultNumberPrefixParser = DefaultNumberPrefixParser;
+const DisabledNumberPrefixParser = (filename) => ({ filename, numberPrefix: undefined });
+exports.DisabledNumberPrefixParser = DisabledNumberPrefixParser;
+// 0-myDoc => myDoc
+function stripNumberPrefix(str, parser) {
+    return parser(str).filename;
+}
+// 0-myFolder/0-mySubfolder/0-myDoc => myFolder/mySubfolder/myDoc
+function stripPathNumberPrefixes(path, parser) {
+    return path
+        .split('/')
+        .map((segment) => stripNumberPrefix(segment, parser))
+        .join('/');
+}

package/lib/options.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 { OptionValidationContext } from '@docusaurus/types';
+import type { PluginOptions, Options } from '@docusaurus/plugin-content-docs';
+export declare const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'>;
+export declare function validateOptions({ validate, options: userOptions, }: OptionValidationContext<Options, PluginOptions>): PluginOptions;

package/lib/options.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.DEFAULT_OPTIONS = void 0;
+exports.validateOptions = validateOptions;
+const tslib_1 = require("tslib");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_validation_1 = require("@docusaurus/utils-validation");
+const glob_1 = require("@docusaurus/glob");
+const generator_1 = require("./sidebars/generator");
+const numberPrefix_1 = require("./numberPrefix");
+exports.DEFAULT_OPTIONS = {
+    path: 'docs', // Path to data on filesystem, relative to site dir.
+    routeBasePath: 'docs', // URL Route.
+    tagsBasePath: 'tags', // URL Tags Route.
+    include: ['**/*.{md,mdx}'], // Extensions to include.
+    exclude: glob_1.GlobExcludeDefault,
+    sidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
+    numberPrefixParser: numberPrefix_1.DefaultNumberPrefixParser,
+    docsRootComponent: '@theme/DocsRoot',
+    docVersionRootComponent: '@theme/DocVersionRoot',
+    docRootComponent: '@theme/DocRoot',
+    docItemComponent: '@theme/DocItem',
+    docTagDocListComponent: '@theme/DocTagDocListPage',
+    docTagsListComponent: '@theme/DocTagsListPage',
+    docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage',
+    remarkPlugins: [],
+    rehypePlugins: [],
+    recmaPlugins: [],
+    beforeDefaultRemarkPlugins: [],
+    beforeDefaultRehypePlugins: [],
+    showLastUpdateTime: false,
+    showLastUpdateAuthor: false,
+    admonitions: true,
+    includeCurrentVersion: true,
+    disableVersioning: false,
+    lastVersion: undefined,
+    versions: {},
+    editCurrentVersion: false,
+    editLocalizedFiles: false,
+    sidebarCollapsible: true,
+    sidebarCollapsed: true,
+    breadcrumbs: true,
+    onInlineTags: 'warn',
+    tags: undefined,
+};
+const VersionOptionsSchema = utils_validation_1.Joi.object({
+    path: utils_validation_1.Joi.string().allow('').optional(),
+    label: utils_validation_1.Joi.string().optional(),
+    banner: utils_validation_1.Joi.string().equal('none', 'unreleased', 'unmaintained').optional(),
+    badge: utils_validation_1.Joi.boolean().optional(),
+    className: utils_validation_1.Joi.string().optional(),
+    noIndex: utils_validation_1.Joi.boolean().optional(),
+});
+const VersionsOptionsSchema = utils_validation_1.Joi.object()
+    .pattern(utils_validation_1.Joi.string().required(), VersionOptionsSchema)
+    .default(exports.DEFAULT_OPTIONS.versions);
+const OptionsSchema = utils_validation_1.Joi.object({
+    path: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.path),
+    editUrl: utils_validation_1.Joi.alternatives().try(utils_validation_1.URISchema, utils_validation_1.Joi.function()),
+    editCurrentVersion: utils_validation_1.Joi.boolean().default(exports.DEFAULT_OPTIONS.editCurrentVersion),
+    editLocalizedFiles: utils_validation_1.Joi.boolean().default(exports.DEFAULT_OPTIONS.editLocalizedFiles),
+    routeBasePath: utils_validation_1.RouteBasePathSchema.default(exports.DEFAULT_OPTIONS.routeBasePath),
+    tagsBasePath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.tagsBasePath),
+    // @ts-expect-error: deprecated
+    homePageId: utils_validation_1.Joi.any().forbidden().messages({
+        'any.unknown': 'The docs plugin option homePageId is not supported anymore. To make a doc the "home", please add "slug: /" in its front matter. See: https://docusaurus.io/docs/next/docs-introduction#home-page-docs',
+    }),
+    include: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.include),
+    exclude: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.exclude),
+    sidebarPath: utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.boolean().invalid(true), utils_validation_1.Joi.string()),
+    sidebarItemsGenerator: utils_validation_1.Joi.function().default(() => exports.DEFAULT_OPTIONS.sidebarItemsGenerator),
+    sidebarCollapsible: utils_validation_1.Joi.boolean().default(exports.DEFAULT_OPTIONS.sidebarCollapsible),
+    sidebarCollapsed: utils_validation_1.Joi.boolean().default(exports.DEFAULT_OPTIONS.sidebarCollapsed),
+    numberPrefixParser: utils_validation_1.Joi.alternatives()
+        .try(utils_validation_1.Joi.function(), 
+    // Convert boolean values to functions
+    utils_validation_1.Joi.alternatives().conditional(utils_validation_1.Joi.boolean(), {
+        then: utils_validation_1.Joi.custom((val) => val ? numberPrefix_1.DefaultNumberPrefixParser : numberPrefix_1.DisabledNumberPrefixParser),
+    }))
+        .default(() => exports.DEFAULT_OPTIONS.numberPrefixParser),
+    docsRootComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docsRootComponent),
+    docVersionRootComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docVersionRootComponent),
+    docRootComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docRootComponent),
+    docItemComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docItemComponent),
+    docTagsListComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docTagsListComponent),
+    docTagDocListComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docTagDocListComponent),
+    docCategoryGeneratedIndexComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docCategoryGeneratedIndexComponent),
+    remarkPlugins: utils_validation_1.RemarkPluginsSchema.default(exports.DEFAULT_OPTIONS.remarkPlugins),
+    rehypePlugins: utils_validation_1.RehypePluginsSchema.default(exports.DEFAULT_OPTIONS.rehypePlugins),
+    recmaPlugins: utils_validation_1.RecmaPluginsSchema.default(exports.DEFAULT_OPTIONS.recmaPlugins),
+    beforeDefaultRemarkPlugins: utils_validation_1.RemarkPluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRemarkPlugins),
+    beforeDefaultRehypePlugins: utils_validation_1.RehypePluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRehypePlugins),
+    admonitions: utils_validation_1.AdmonitionsSchema.default(exports.DEFAULT_OPTIONS.admonitions),
+    showLastUpdateTime: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateTime),
+    showLastUpdateAuthor: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateAuthor),
+    includeCurrentVersion: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.includeCurrentVersion),
+    onlyIncludeVersions: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string().required()).optional(),
+    disableVersioning: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.disableVersioning),
+    lastVersion: utils_validation_1.Joi.string().optional(),
+    versions: VersionsOptionsSchema,
+    breadcrumbs: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.breadcrumbs),
+    onInlineTags: utils_validation_1.Joi.string()
+        .equal('ignore', 'log', 'warn', 'throw')
+        .default(exports.DEFAULT_OPTIONS.onInlineTags),
+    tags: utils_validation_1.Joi.string()
+        .disallow('')
+        .allow(null, false)
+        .default(() => exports.DEFAULT_OPTIONS.tags),
+});
+function validateOptions({ validate, options: userOptions, }) {
+    let options = userOptions;
+    if (options.sidebarCollapsible === false) {
+        // When sidebarCollapsible=false and sidebarCollapsed=undefined, we don't
+        // want to have the inconsistency warning. We let options.sidebarCollapsible
+        // become the default value for options.sidebarCollapsed
+        if (typeof options.sidebarCollapsed === 'undefined') {
+            options = {
+                ...options,
+                sidebarCollapsed: false,
+            };
+        }
+        if (options.sidebarCollapsed) {
+            logger_1.default.warn `The docs plugin config is inconsistent. It does not make sense to use code=${'sidebarCollapsible: false'} and code=${'sidebarCollapsed: true'} at the same time. code=${'sidebarCollapsed: true'} will be ignored.`;
+            options = {
+                ...options,
+                sidebarCollapsed: false,
+            };
+        }
+    }
+    const normalizedOptions = validate(OptionsSchema, options);
+    return normalizedOptions;
+}

package/lib/props.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { VersionTag, VersionTags } from './types';
+import type { SidebarItemDoc } from './sidebars/types';
+import type { PropSidebars, PropVersionMetadata, PropTagDocList, PropTagsListPage, PropSidebarItemLink, DocMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
+export declare function toSidebarDocItemLinkProp({ item, doc, }: {
+    item: SidebarItemDoc;
+    doc: Pick<DocMetadata, 'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter'>;
+}): PropSidebarItemLink;
+export declare function toSidebarsProp(loadedVersion: Pick<LoadedVersion, 'docs' | 'sidebars'>): PropSidebars;
+export declare function toVersionMetadataProp(pluginId: string, loadedVersion: LoadedVersion): PropVersionMetadata;
+export declare function toTagDocListProp({ allTagsPath, tag, docs, }: {
+    allTagsPath: string;
+    tag: VersionTag;
+    docs: DocMetadata[];
+}): PropTagDocList;
+export declare function toTagsListTagsProp(versionTags: VersionTags): PropTagsListPage['tags'];

package/lib/props.js

@@ -0,0 +1,156 @@
+"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.toSidebarDocItemLinkProp = toSidebarDocItemLinkProp;
+exports.toSidebarsProp = toSidebarsProp;
+exports.toVersionMetadataProp = toVersionMetadataProp;
+exports.toTagDocListProp = toTagDocListProp;
+exports.toTagsListTagsProp = toTagsListTagsProp;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const docs_1 = require("./docs");
+function toSidebarDocItemLinkProp({ item, doc, }) {
+    const { id, title, permalink, frontMatter, unlisted } = doc;
+    return {
+        type: 'link',
+        ...(item.key && { key: item.key }),
+        href: permalink,
+        // Front Matter data takes precedence over sidebars.json
+        label: frontMatter.sidebar_label ?? item.label ?? title,
+        className: frontMatter.sidebar_class_name ?? item.className,
+        customProps: frontMatter.sidebar_custom_props ?? item.customProps,
+        docId: id,
+        unlisted,
+    };
+}
+function toSidebarsProp(loadedVersion) {
+    const docsById = (0, docs_1.createDocsByIdIndex)(loadedVersion.docs);
+    function getDocById(docId) {
+        const docMetadata = docsById[docId];
+        if (!docMetadata) {
+            throw new Error(`Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
+Available document ids are:
+- ${Object.keys(docsById).sort().join('\n- ')}`);
+        }
+        return docMetadata;
+    }
+    const convertDocLink = (item) => {
+        const doc = getDocById(item.id);
+        return toSidebarDocItemLinkProp({ item, doc });
+    };
+    function getCategoryLinkHref(link) {
+        switch (link?.type) {
+            case 'doc':
+                return getDocById(link.id).permalink;
+            case 'generated-index':
+                return link.permalink;
+            default:
+                return undefined;
+        }
+    }
+    function getCategoryLinkUnlisted(link) {
+        if (link?.type === 'doc') {
+            return getDocById(link.id).unlisted;
+        }
+        return false;
+    }
+    function getCategoryLinkCustomProps(link) {
+        switch (link?.type) {
+            case 'doc':
+                return getDocById(link.id).frontMatter.sidebar_custom_props;
+            default:
+                return undefined;
+        }
+    }
+    function convertCategory(item) {
+        const { link, ...rest } = item;
+        const href = getCategoryLinkHref(link);
+        const linkUnlisted = getCategoryLinkUnlisted(link);
+        const customProps = item.customProps ?? getCategoryLinkCustomProps(link);
+        return {
+            ...rest,
+            items: item.items.map(normalizeItem),
+            ...(href && { href }),
+            ...(linkUnlisted && { linkUnlisted }),
+            ...(customProps && { customProps }),
+        };
+    }
+    function normalizeItem(item) {
+        switch (item.type) {
+            case 'category':
+                return convertCategory(item);
+            case 'ref':
+            case 'doc':
+                return convertDocLink(item);
+            case 'link':
+            default:
+                return item;
+        }
+    }
+    // Transform the sidebar so that all sidebar item will be in the
+    // form of 'link' or 'category' only.
+    // This is what will be passed as props to the UI component.
+    return lodash_1.default.mapValues(loadedVersion.sidebars, (items) => items.map(normalizeItem));
+}
+function toVersionDocsProp(loadedVersion) {
+    return Object.fromEntries(loadedVersion.docs.map((doc) => [
+        doc.id,
+        {
+            id: doc.id,
+            title: doc.title,
+            description: doc.description,
+            sidebar: doc.sidebar,
+        },
+    ]));
+}
+function toVersionMetadataProp(pluginId, loadedVersion) {
+    return {
+        pluginId,
+        version: loadedVersion.versionName,
+        label: loadedVersion.label,
+        banner: loadedVersion.banner,
+        badge: loadedVersion.badge,
+        noIndex: loadedVersion.noIndex,
+        className: loadedVersion.className,
+        isLast: loadedVersion.isLast,
+        docsSidebars: toSidebarsProp(loadedVersion),
+        docs: toVersionDocsProp(loadedVersion),
+    };
+}
+function toTagDocListProp({ allTagsPath, tag, docs, }) {
+    function toDocListProp() {
+        const list = lodash_1.default.compact(tag.docIds.map((id) => docs.find((doc) => doc.id === id)));
+        // Sort docs by title
+        list.sort((doc1, doc2) => doc1.title.localeCompare(doc2.title));
+        return list.map((doc) => ({
+            id: doc.id,
+            title: doc.title,
+            description: doc.description,
+            permalink: doc.permalink,
+        }));
+    }
+    return {
+        label: tag.label,
+        permalink: tag.permalink,
+        description: tag.description,
+        allTagsPath,
+        count: tag.docIds.length,
+        items: toDocListProp(),
+        unlisted: tag.unlisted,
+    };
+}
+function toTagsListTagsProp(versionTags) {
+    return Object.values(versionTags)
+        .filter((tagValue) => !tagValue.unlisted)
+        .map((tagValue) => ({
+        label: tagValue.label,
+        permalink: tagValue.permalink,
+        description: tagValue.description,
+        count: tagValue.docIds.length,
+    }));
+}

package/lib/routes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { PluginContentLoadedActions, RouteConfig } from '@docusaurus/types';
+import type { FullVersion } from './types';
+import type { PluginOptions } from '@docusaurus/plugin-content-docs';
+type BuildAllRoutesParam = Omit<CreateAllRoutesParam, 'actions'> & {
+    actions: Omit<PluginContentLoadedActions, 'addRoute' | 'setGlobalData'>;
+};
+export declare function buildAllRoutes(param: BuildAllRoutesParam): Promise<RouteConfig[]>;
+type CreateAllRoutesParam = {
+    baseUrl: string;
+    versions: FullVersion[];
+    options: PluginOptions;
+    actions: PluginContentLoadedActions;
+    aliasedSource: (str: string) => string;
+};
+export declare function createAllRoutes(param: CreateAllRoutesParam): Promise<void>;
+export {};