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

package/lib/translations.js

@@ -0,0 +1,243 @@
+"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.getLoadedContentTranslationFiles = getLoadedContentTranslationFiles;
+exports.translateLoadedContent = translateLoadedContent;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("@docusaurus/utils");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const constants_1 = require("./constants");
+const utils_2 = require("./sidebars/utils");
+function getVersionFileName(versionName) {
+    if (versionName === constants_1.CURRENT_VERSION_NAME) {
+        return versionName;
+    }
+    // I don't like this "version-" prefix,
+    // but it's for consistency with site/versioned_docs
+    return `version-${versionName}`;
+}
+function ensureNoSidebarDuplicateEntries(translationEntries) {
+    const grouped = lodash_1.default.groupBy(translationEntries, (entry) => entry[0]);
+    const duplicates = Object.entries(grouped).filter((entry) => entry[1].length > 1);
+    if (duplicates.length > 0) {
+        throw new Error(`Multiple docs sidebar items produce the same translation key.
+- ${duplicates
+            .map(([translationKey, entries]) => {
+            return `${logger_1.default.code(translationKey)}: ${logger_1.default.num(entries.length)} duplicates found:\n  - ${entries
+                .map((duplicate) => {
+                const desc = duplicate[1].description;
+                return `${logger_1.default.name(duplicate[1].message)} ${desc ? `(${logger_1.default.subdue(desc)})` : ''}`;
+            })
+                .join('\n  - ')}`;
+        })
+            .join('\n\n- ')}
+
+To avoid translation key conflicts, use the ${logger_1.default.code('key')} attribute on the sidebar items above to uniquely identify them.
+
+When using autogenerated sidebars, you can provide a unique translation key by adding:
+- the ${logger_1.default.code('key')} attribute to category item metadata (${logger_1.default.code('_category_.json')} / ${logger_1.default.code('_category_.yml')})
+- the ${logger_1.default.code('sidebar_key')} attribute to doc item metadata (front matter in ${logger_1.default.code('Category/index.mdx')})`);
+    }
+}
+function getSidebarTranslationFileContent(sidebar, sidebarName) {
+    const categories = (0, utils_2.collectSidebarCategories)(sidebar);
+    const categoryEntries = categories.flatMap((category) => {
+        const entries = [];
+        const categoryKey = category.key ?? category.label;
+        entries.push([
+            `sidebar.${sidebarName}.category.${categoryKey}`,
+            {
+                message: category.label,
+                description: `The label for category '${category.label}' in sidebar '${sidebarName}'`,
+            },
+        ]);
+        if (category.link?.type === 'generated-index') {
+            if (category.link.title) {
+                entries.push([
+                    `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.title`,
+                    {
+                        message: category.link.title,
+                        description: `The generated-index page title for category '${category.label}' in sidebar '${sidebarName}'`,
+                    },
+                ]);
+            }
+            if (category.link.description) {
+                entries.push([
+                    `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.description`,
+                    {
+                        message: category.link.description,
+                        description: `The generated-index page description for category '${category.label}' in sidebar '${sidebarName}'`,
+                    },
+                ]);
+            }
+        }
+        return entries;
+    });
+    const links = (0, utils_2.collectSidebarLinks)(sidebar);
+    const linksEntries = links.map((link) => {
+        const linkKey = link.key ?? link.label;
+        return [
+            `sidebar.${sidebarName}.link.${linkKey}`,
+            {
+                message: link.label,
+                description: `The label for link '${link.label}' in sidebar '${sidebarName}', linking to '${link.href}'`,
+            },
+        ];
+    });
+    const docs = (0, utils_2.collectSidebarDocItems)(sidebar)
+        .concat((0, utils_2.collectSidebarRefs)(sidebar))
+        .filter((item) => item.translatable);
+    const docLinksEntries = docs.map((doc) => {
+        const docKey = doc.key ?? doc.label;
+        return [
+            `sidebar.${sidebarName}.doc.${docKey}`,
+            {
+                message: doc.label,
+                description: `The label for the doc item '${doc.label}' in sidebar '${sidebarName}', linking to the doc ${doc.id}`,
+            },
+        ];
+    });
+    const allEntries = [...categoryEntries, ...linksEntries, ...docLinksEntries];
+    ensureNoSidebarDuplicateEntries(allEntries);
+    return Object.fromEntries(allEntries);
+}
+function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
+    function transformSidebarCategoryLink(category) {
+        if (!category.link) {
+            return undefined;
+        }
+        if (category.link.type === 'generated-index') {
+            const categoryKey = category.key ?? category.label;
+            const title = sidebarsTranslations[`sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.title`]?.message ?? category.link.title;
+            const description = sidebarsTranslations[`sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.description`]?.message ?? category.link.description;
+            return {
+                ...category.link,
+                title,
+                description,
+            };
+        }
+        return category.link;
+    }
+    return (0, utils_2.transformSidebarItems)(sidebar, (item) => {
+        if (item.type === 'category') {
+            const link = transformSidebarCategoryLink(item);
+            const categoryKey = item.key ?? item.label;
+            return {
+                ...item,
+                label: sidebarsTranslations[`sidebar.${sidebarName}.category.${categoryKey}`]
+                    ?.message ?? item.label,
+                ...(link && { link }),
+            };
+        }
+        if (item.type === 'link') {
+            const linkKey = item.key ?? item.label;
+            return {
+                ...item,
+                label: sidebarsTranslations[`sidebar.${sidebarName}.link.${linkKey}`]
+                    ?.message ?? item.label,
+            };
+        }
+        if ((item.type === 'doc' || item.type === 'ref') && item.translatable) {
+            const docKey = item.key ?? item.label;
+            return {
+                ...item,
+                label: sidebarsTranslations[`sidebar.${sidebarName}.doc.${docKey}`]
+                    ?.message ?? item.label,
+            };
+        }
+        return item;
+    });
+}
+function getSidebarsTranslations(version) {
+    return (0, utils_1.mergeTranslations)(Object.entries(version.sidebars).map(([sidebarName, sidebar]) => getSidebarTranslationFileContent(sidebar, sidebarName)));
+}
+function translateSidebars(version, sidebarsTranslations) {
+    return lodash_1.default.mapValues(version.sidebars, (sidebar, sidebarName) => translateSidebar({
+        sidebar,
+        sidebarName,
+        sidebarsTranslations,
+    }));
+}
+function getVersionTranslationFiles(version) {
+    const versionTranslations = {
+        'version.label': {
+            message: version.label,
+            description: `The label for version ${version.versionName}`,
+        },
+    };
+    const sidebarsTranslations = getSidebarsTranslations(version);
+    return [
+        {
+            path: getVersionFileName(version.versionName),
+            content: (0, utils_1.mergeTranslations)([versionTranslations, sidebarsTranslations]),
+        },
+    ];
+}
+// TODO Docusaurus v4 or later
+//  this temporarily works, but it is not an ideal solution
+//  The docs navigation can be computed and shouldn't be part of LoadedVersion
+//  We need to derive the navigation from already translated content
+//  See https://github.com/facebook/docusaurus/pull/11794
+function translateDocNavigation(docs, translatedSidebars) {
+    // Build a map of permalink -> translated label for generated-index categories
+    const translatedLabelByPermalink = new Map();
+    for (const sidebar of Object.values(translatedSidebars)) {
+        for (const category of (0, utils_2.collectSidebarCategories)(sidebar)) {
+            if (category.link?.type === 'generated-index') {
+                translatedLabelByPermalink.set(category.link.permalink, category.label);
+            }
+        }
+    }
+    if (translatedLabelByPermalink.size === 0) {
+        return docs;
+    }
+    return docs.map((doc) => {
+        const previous = doc.previous && translatedLabelByPermalink.has(doc.previous.permalink)
+            ? {
+                ...doc.previous,
+                title: translatedLabelByPermalink.get(doc.previous.permalink),
+            }
+            : doc.previous;
+        const next = doc.next && translatedLabelByPermalink.has(doc.next.permalink)
+            ? {
+                ...doc.next,
+                title: translatedLabelByPermalink.get(doc.next.permalink),
+            }
+            : doc.next;
+        if (previous === doc.previous && next === doc.next) {
+            return doc;
+        }
+        return { ...doc, previous, next };
+    });
+}
+function translateVersion(version, translationFiles) {
+    const versionTranslations = translationFiles[getVersionFileName(version.versionName)].content;
+    const translatedSidebars = translateSidebars(version, versionTranslations);
+    return {
+        ...version,
+        label: versionTranslations['version.label']?.message ?? version.label,
+        sidebars: translatedSidebars,
+        docs: translateDocNavigation(version.docs, translatedSidebars),
+    };
+}
+function getVersionsTranslationFiles(versions) {
+    return versions.flatMap(getVersionTranslationFiles);
+}
+function translateVersions(versions, translationFiles) {
+    return versions.map((version) => translateVersion(version, translationFiles));
+}
+function getLoadedContentTranslationFiles(loadedContent) {
+    return getVersionsTranslationFiles(loadedContent.loadedVersions);
+}
+function translateLoadedContent(loadedContent, translationFiles) {
+    const translationFilesMap = lodash_1.default.keyBy(translationFiles, (f) => f.path);
+    return {
+        loadedVersions: translateVersions(loadedContent.loadedVersions, translationFilesMap),
+    };
+}

package/lib/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { TagMetadata } from '@docusaurus/utils';
+import type { LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
+import type { SidebarsUtils } from './sidebars/utils';
+export type DocFile = {
+    contentPath: string;
+    filePath: string;
+    source: string;
+    content: string;
+};
+export type VersionTag = TagMetadata & {
+    /** All doc ids having this tag. */
+    docIds: string[];
+    unlisted: boolean;
+};
+export type VersionTags = {
+    [permalink: string]: VersionTag;
+};
+export type FullVersion = LoadedVersion & {
+    sidebarsUtils: SidebarsUtils;
+    categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
+};

package/lib/types.js

@@ -0,0 +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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/versions/files.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 { PluginOptions, VersionMetadata } from '@docusaurus/plugin-content-docs';
+import type { VersionContext } from './version';
+/** `[siteDir]/community_versioned_docs/version-1.0.0` */
+export declare function getVersionDocsDirPath(siteDir: string, pluginId: string, versionName: string): string;
+/** `[siteDir]/community_versioned_sidebars/version-1.0.0-sidebars.json` */
+export declare function getVersionSidebarsPath(siteDir: string, pluginId: string, versionName: string): string;
+export declare function getDocsDirPathLocalized({ localizationDir, pluginId, versionName, }: {
+    localizationDir: string;
+    pluginId: string;
+    versionName: string;
+}): string;
+export declare function getPluginDirPathLocalized({ localizationDir, pluginId, }: {
+    localizationDir: string;
+    pluginId: string;
+}): string;
+/** `community` => `[siteDir]/community_versions.json` */
+export declare function getVersionsFilePath(siteDir: string, pluginId: string): string;
+/**
+ * Reads the plugin's respective `versions.json` file, and returns its content.
+ *
+ * @throws Throws if validation fails, i.e. `versions.json` doesn't contain an
+ * array of valid version names.
+ */
+export declare function readVersionsFile(siteDir: string, pluginId: string): Promise<string[] | null>;
+/**
+ * Reads the `versions.json` file, and returns an ordered list of version names.
+ *
+ * - If `disableVersioning` is turned on, it will return `["current"]` (requires
+ * `includeCurrentVersion` to be true);
+ * - If `includeCurrentVersion` is turned on, "current" will be inserted at the
+ * beginning, if not already there.
+ *
+ * You need to use {@link filterVersions} after this.
+ *
+ * @throws Throws an error if `disableVersioning: true` but `versions.json`
+ * doesn't exist (i.e. site is not versioned)
+ * @throws Throws an error if versions list is empty (empty `versions.json` or
+ * `disableVersioning` is true, and not including current version)
+ */
+export declare function readVersionNames(siteDir: string, options: PluginOptions): Promise<string[]>;
+/**
+ * Gets the path-related version metadata.
+ *
+ * @throws Throws if the resolved docs folder or sidebars file doesn't exist.
+ * Does not throw if a versioned sidebar is missing (since we don't create empty
+ * files).
+ */
+export declare function getVersionMetadataPaths({ versionName, context, options, }: VersionContext): Promise<Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized' | 'sidebarFilePath'>>;

package/lib/versions/files.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.getVersionDocsDirPath = getVersionDocsDirPath;
+exports.getVersionSidebarsPath = getVersionSidebarsPath;
+exports.getDocsDirPathLocalized = getDocsDirPathLocalized;
+exports.getPluginDirPathLocalized = getPluginDirPathLocalized;
+exports.getVersionsFilePath = getVersionsFilePath;
+exports.readVersionsFile = readVersionsFile;
+exports.readVersionNames = readVersionNames;
+exports.getVersionMetadataPaths = getVersionMetadataPaths;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const utils_1 = require("@docusaurus/utils");
+const fs_1 = require("@docusaurus/fs");
+const constants_1 = require("../constants");
+const validation_1 = require("./validation");
+/** Add a prefix like `community_version-1.0.0`. No-op for default instance. */
+function addPluginIdPrefix(fileOrDir, pluginId) {
+    return pluginId === utils_1.DEFAULT_PLUGIN_ID
+        ? fileOrDir
+        : `${pluginId}_${fileOrDir}`;
+}
+/** `[siteDir]/community_versioned_docs/version-1.0.0` */
+function getVersionDocsDirPath(siteDir, pluginId, versionName) {
+    return node_path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_DOCS_DIR, pluginId), `version-${versionName}`);
+}
+/** `[siteDir]/community_versioned_sidebars/version-1.0.0-sidebars.json` */
+function getVersionSidebarsPath(siteDir, pluginId, versionName) {
+    return node_path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_SIDEBARS_DIR, pluginId), `version-${versionName}-sidebars.json`);
+}
+function getDocsDirPathLocalized({ localizationDir, pluginId, versionName, }) {
+    return (0, utils_1.getPluginI18nPath)({
+        localizationDir,
+        pluginName: 'docusaurus-plugin-content-docs',
+        pluginId,
+        subPaths: [
+            versionName === constants_1.CURRENT_VERSION_NAME
+                ? constants_1.CURRENT_VERSION_NAME
+                : `version-${versionName}`,
+        ],
+    });
+}
+function getPluginDirPathLocalized({ localizationDir, pluginId, }) {
+    return (0, utils_1.getPluginI18nPath)({
+        localizationDir,
+        pluginName: 'docusaurus-plugin-content-docs',
+        pluginId,
+        subPaths: [],
+    });
+}
+/** `community` => `[siteDir]/community_versions.json` */
+function getVersionsFilePath(siteDir, pluginId) {
+    return node_path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONS_JSON_FILE, pluginId));
+}
+/**
+ * Reads the plugin's respective `versions.json` file, and returns its content.
+ *
+ * @throws Throws if validation fails, i.e. `versions.json` doesn't contain an
+ * array of valid version names.
+ */
+async function readVersionsFile(siteDir, pluginId) {
+    const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
+    if (await (0, fs_1.pathExists)(versionsFilePath)) {
+        const content = await (0, fs_1.readJSON)(versionsFilePath);
+        (0, validation_1.validateVersionNames)(content);
+        return content;
+    }
+    return null;
+}
+/**
+ * Reads the `versions.json` file, and returns an ordered list of version names.
+ *
+ * - If `disableVersioning` is turned on, it will return `["current"]` (requires
+ * `includeCurrentVersion` to be true);
+ * - If `includeCurrentVersion` is turned on, "current" will be inserted at the
+ * beginning, if not already there.
+ *
+ * You need to use {@link filterVersions} after this.
+ *
+ * @throws Throws an error if `disableVersioning: true` but `versions.json`
+ * doesn't exist (i.e. site is not versioned)
+ * @throws Throws an error if versions list is empty (empty `versions.json` or
+ * `disableVersioning` is true, and not including current version)
+ */
+async function readVersionNames(siteDir, options) {
+    const versionFileContent = await readVersionsFile(siteDir, options.id);
+    if (!versionFileContent && options.disableVersioning) {
+        throw new Error(`Docs: using "disableVersioning: true" option on a non-versioned site does not make sense.`);
+    }
+    const versions = options.disableVersioning ? [] : (versionFileContent ?? []);
+    // We add the current version at the beginning, unless:
+    // - user don't want to; or
+    // - it's already been explicitly added to versions.json
+    if (options.includeCurrentVersion &&
+        !versions.includes(constants_1.CURRENT_VERSION_NAME)) {
+        versions.unshift(constants_1.CURRENT_VERSION_NAME);
+    }
+    if (versions.length === 0) {
+        throw new Error(`It is not possible to use docs without any version. No version is included because you have requested to not include ${node_path_1.default.resolve(options.path)} through "includeCurrentVersion: false", while ${options.disableVersioning
+            ? 'versioning is disabled with "disableVersioning: true"'
+            : `the versions file is empty/non-existent`}.`);
+    }
+    return versions;
+}
+/**
+ * Gets the path-related version metadata.
+ *
+ * @throws Throws if the resolved docs folder or sidebars file doesn't exist.
+ * Does not throw if a versioned sidebar is missing (since we don't create empty
+ * files).
+ */
+async function getVersionMetadataPaths({ versionName, context, options, }) {
+    const isCurrent = versionName === constants_1.CURRENT_VERSION_NAME;
+    const shouldTranslate = (0, utils_1.getLocaleConfig)(context.i18n).translate;
+    const contentPathLocalized = shouldTranslate
+        ? getDocsDirPathLocalized({
+            localizationDir: context.localizationDir,
+            pluginId: options.id,
+            versionName,
+        })
+        : undefined;
+    const contentPath = isCurrent
+        ? node_path_1.default.resolve(context.siteDir, options.path)
+        : getVersionDocsDirPath(context.siteDir, options.id, versionName);
+    const sidebarFilePath = isCurrent
+        ? options.sidebarPath
+        : getVersionSidebarsPath(context.siteDir, options.id, versionName);
+    if (!(await (0, fs_1.pathExists)(contentPath))) {
+        throw new Error(`The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${node_path_1.default.relative(context.siteDir, contentPath)}.`);
+    }
+    // If the current version defines a path to a sidebar file that does not
+    // exist, we throw! Note: for versioned sidebars, the file may not exist (as
+    // we prefer to not create it rather than to create an empty file)
+    // See https://github.com/facebook/docusaurus/issues/3366
+    // See https://github.com/facebook/docusaurus/pull/4775
+    if (versionName === constants_1.CURRENT_VERSION_NAME &&
+        typeof sidebarFilePath === 'string' &&
+        !(await (0, fs_1.pathExists)(sidebarFilePath))) {
+        throw new Error(`The path to the sidebar file does not exist at "${node_path_1.default.relative(context.siteDir, sidebarFilePath)}".
+Please set the docs "sidebarPath" field in your config file to:
+- a sidebars path that exists
+- false: to disable the sidebar
+- undefined: for Docusaurus to generate it automatically`);
+    }
+    return { contentPath, contentPathLocalized, sidebarFilePath };
+}

package/lib/versions/loadVersion.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 DocEnv } from '../docs';
+import type { LoadedVersion, PluginOptions, VersionMetadata } from '@docusaurus/plugin-content-docs';
+import type { LoadContext } from '@docusaurus/types';
+type LoadVersionParams = {
+    context: LoadContext;
+    options: PluginOptions;
+    versionMetadata: VersionMetadata;
+    env: DocEnv;
+};
+export declare function loadVersion(params: LoadVersionParams): Promise<LoadedVersion>;
+export {};

package/lib/versions/loadVersion.js

@@ -0,0 +1,126 @@
+"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.loadVersion = loadVersion;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("@docusaurus/utils");
+const utils_validation_1 = require("@docusaurus/utils-validation");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const docs_1 = require("../docs");
+const sidebars_1 = require("../sidebars");
+const utils_2 = require("../sidebars/utils");
+function ensureNoDuplicateDocId(docs) {
+    const duplicatesById = lodash_1.default.chain(docs)
+        .sort((d1, d2) => {
+        // Need to sort because glob order is non-deterministic
+        // TODO maybe we should create a deterministic glob utils?
+        //  see https://github.com/sindresorhus/globby/issues/131
+        return d1.source.localeCompare(d2.source);
+    })
+        .groupBy((d) => d.id)
+        .pickBy((group) => group.length > 1)
+        .value();
+    const duplicateIdEntries = Object.entries(duplicatesById);
+    if (duplicateIdEntries.length) {
+        const idMessages = duplicateIdEntries
+            .map(([id, duplicateDocs]) => {
+            return logger_1.default.interpolate `- code=${id} found in number=${duplicateDocs.length} docs:
+  - ${duplicateDocs
+                .map((d) => (0, utils_1.aliasedSitePathToRelativePath)(d.source))
+                .join('\n  - ')}`;
+        })
+            .join('\n\n');
+        const message = `The docs plugin found docs sharing the same id:
+\n${idMessages}\n
+Docs should have distinct ids.
+In case of conflict, you can rename the docs file, or use the ${logger_1.default.code('id')} front matter to assign an explicit distinct id to each doc.
+    `;
+        throw new Error(message);
+    }
+}
+async function loadVersionDocsBase({ tagsFile, context, options, versionMetadata, env, }) {
+    const docFiles = await (0, docs_1.readVersionDocs)(versionMetadata, options);
+    if (docFiles.length === 0) {
+        throw new Error(`Docs version "${versionMetadata.versionName}" has no docs! At least one doc should exist at "${node_path_1.default.relative(context.siteDir, versionMetadata.contentPath)}".`);
+    }
+    function processVersionDoc(docFile) {
+        return (0, docs_1.processDocMetadata)({
+            docFile,
+            versionMetadata,
+            context,
+            options,
+            env,
+            tagsFile,
+        });
+    }
+    const docs = await Promise.all(docFiles.map(processVersionDoc));
+    ensureNoDuplicateDocId(docs);
+    return docs;
+}
+async function doLoadVersion({ context, options, versionMetadata, env, }) {
+    const tagsFile = await (0, utils_validation_1.getTagsFile)({
+        contentPaths: versionMetadata,
+        tags: options.tags,
+    });
+    const docsBase = await loadVersionDocsBase({
+        tagsFile,
+        context,
+        options,
+        versionMetadata,
+        env,
+    });
+    // TODO we only ever need draftIds in further code, not full draft items
+    // To simplify and prevent mistakes, avoid exposing draft
+    // replace draft=>draftIds in content loaded
+    const [drafts, docs] = lodash_1.default.partition(docsBase, (doc) => doc.draft);
+    const sidebars = await (0, sidebars_1.loadSidebars)(versionMetadata.sidebarFilePath, {
+        sidebarItemsGenerator: options.sidebarItemsGenerator,
+        numberPrefixParser: options.numberPrefixParser,
+        docs,
+        drafts,
+        version: versionMetadata,
+        sidebarOptions: {
+            sidebarCollapsed: options.sidebarCollapsed,
+            sidebarCollapsible: options.sidebarCollapsible,
+        },
+        categoryLabelSlugger: (0, utils_1.createSlugger)(),
+    });
+    const sidebarsUtils = (0, utils_2.createSidebarsUtils)(sidebars);
+    const docsById = (0, docs_1.createDocsByIdIndex)(docs);
+    const allDocIds = Object.keys(docsById);
+    sidebarsUtils.checkLegacyVersionedSidebarNames({
+        sidebarFilePath: versionMetadata.sidebarFilePath,
+        versionMetadata,
+    });
+    sidebarsUtils.checkSidebarsDocIds({
+        allDocIds,
+        sidebarFilePath: versionMetadata.sidebarFilePath,
+        versionMetadata,
+    });
+    return {
+        ...versionMetadata,
+        docs: (0, docs_1.addDocNavigation)({
+            docs,
+            sidebarsUtils,
+        }),
+        drafts,
+        sidebars,
+    };
+}
+async function loadVersion(params) {
+    try {
+        return await doLoadVersion(params);
+    }
+    catch (err) {
+        // TODO use error cause (but need to refactor many tests)
+        logger_1.default.error `Loading of version failed for version name=${params.versionMetadata.versionName}`;
+        throw err;
+    }
+}

package/lib/versions/validation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 { VersionsOptions } from '@docusaurus/plugin-content-docs';
+export declare function validateVersionName(name: unknown): asserts name is string;
+export declare function validateVersionNames(names: unknown): asserts names is string[];
+/**
+ * @throws Throws for one of the following invalid options:
+ * - `lastVersion` is non-existent
+ * - `versions` includes unknown keys
+ * - `onlyIncludeVersions` is empty, contains unknown names, or doesn't include
+ * `latestVersion` (if provided)
+ */
+export declare function validateVersionsOptions(availableVersionNames: string[], options: VersionsOptions): void;