@docusaurus/plugin-content-docs 0.0.0-4848 → 0.0.0-4851

package/lib/cli.d.ts

@@ -6,4 +6,4 @@
  */
 import type { PluginOptions } from '@docusaurus/plugin-content-docs';
 import type { LoadContext } from '@docusaurus/types';
-export declare function cliDocsVersionCommand(version: string | null | undefined, { id: pluginId, path: docsPath, sidebarPath }: PluginOptions, { siteDir, i18n }: LoadContext): Promise<void>;
+export declare function cliDocsVersionCommand(version: string, { id: pluginId, path: docsPath, sidebarPath }: PluginOptions, { siteDir, i18n }: LoadContext): Promise<void>;

package/lib/cli.js

@@ -8,7 +8,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cliDocsVersionCommand = void 0;
 const tslib_1 = require("tslib");
-const versions_1 = require("./versions");
+const files_1 = require("./versions/files");
+const validation_1 = require("./versions/validation");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const path_1 = tslib_1.__importDefault(require("path"));
 const sidebars_1 = require("./sidebars");
@@ -25,9 +26,7 @@ async function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, vers
     // or sidebars are disabled/false)
     const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
     if (shouldCreateVersionedSidebarFile) {
-        const versionedSidebarsDir = (0, versions_1.getVersionedSidebarsDirPath)(siteDir, pluginId);
-        const newSidebarFile = path_1.default.join(versionedSidebarsDir, `version-${version}-sidebars.json`);
-        await fs_extra_1.default.outputFile(newSidebarFile, `${JSON.stringify(sidebars, null, 2)}\n`, 'utf8');
+        await fs_extra_1.default.outputFile((0, files_1.getVersionSidebarsPath)(siteDir, pluginId, version), `${JSON.stringify(sidebars, null, 2)}\n`, 'utf8');
     }
 }
 // Tests depend on non-default export for mocking.
@@ -35,29 +34,18 @@ async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, si
     // It wouldn't be very user-friendly to show a [default] log prefix,
     // so we use [docs] instead of [default]
     const pluginIdLogPrefix = pluginId === utils_1.DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
-    if (!version) {
-        throw new Error(`${pluginIdLogPrefix}: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0.`);
+    try {
+        (0, validation_1.validateVersionName)(version);
     }
-    if (version.includes('/') || version.includes('\\')) {
-        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Do not include slash (/) or backslash (\\). Try something like: 1.0.0.`);
-    }
-    if (version.length > 32) {
-        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Length cannot exceed 32 characters. Try something like: 1.0.0.`);
-    }
-    // Since we are going to create `version-${version}` folder, we need to make
-    // sure it's a valid pathname.
-    // eslint-disable-next-line no-control-regex
-    if (/[<>:"|?*\x00-\x1F]/.test(version)) {
-        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0.`);
-    }
-    if (/^\.\.?$/.test(version)) {
-        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0.`);
+    catch (e) {
+        logger_1.default.info `${pluginIdLogPrefix}: Invalid version name provided. Try something like: 1.0.0`;
+        throw e;
     }
     // Load existing versions.
     let versions = [];
-    const versionsJSONFile = (0, versions_1.getVersionsFilePath)(siteDir, pluginId);
+    const versionsJSONFile = (0, files_1.getVersionsFilePath)(siteDir, pluginId);
     if (await fs_extra_1.default.pathExists(versionsJSONFile)) {
-        versions = JSON.parse(await fs_extra_1.default.readFile(versionsJSONFile, 'utf8'));
+        versions = await fs_extra_1.default.readJSON(versionsJSONFile);
     }
     // Check if version already exists.
     if (versions.includes(version)) {
@@ -70,7 +58,7 @@ async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, si
         // Copy docs files.
         const docsDir = locale === i18n.defaultLocale
             ? path_1.default.resolve(siteDir, docsPath)
-            : (0, versions_1.getDocsDirPathLocalized)({
+            : (0, files_1.getDocsDirPathLocalized)({
                 siteDir,
                 locale,
                 pluginId,
@@ -87,8 +75,8 @@ async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, si
             }
         }
         const newVersionDir = locale === i18n.defaultLocale
-            ? path_1.default.join((0, versions_1.getVersionedDocsDirPath)(siteDir, pluginId), `version-${version}`)
-            : (0, versions_1.getDocsDirPathLocalized)({
+            ? (0, files_1.getVersionDocsDirPath)(siteDir, pluginId, version)
+            : (0, files_1.getDocsDirPathLocalized)({
                 siteDir,
                 locale,
                 pluginId,
@@ -100,7 +88,7 @@ async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, si
         siteDir,
         pluginId,
         version,
-        sidebarPath: (0, sidebars_1.resolveSidebarPathOption)(siteDir, sidebarPath),
+        sidebarPath,
     });
     // Update versions.json file.
     versions.unshift(version);

package/lib/constants.d.ts

@@ -4,7 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/** The name of the version that's actively worked on (e.g. `website/docs`) */
 export declare const CURRENT_VERSION_NAME = "current";
+/** All doc versions are stored here by version names */
 export declare const VERSIONED_DOCS_DIR = "versioned_docs";
+/** All doc versioned sidebars are stored here by version names */
 export declare const VERSIONED_SIDEBARS_DIR = "versioned_sidebars";
+/** The version names. Should 1-1 map to the content of versioned docs dir. */
 export declare const VERSIONS_JSON_FILE = "versions.json";

package/lib/constants.js

@@ -7,8 +7,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSIONS_JSON_FILE = exports.VERSIONED_SIDEBARS_DIR = exports.VERSIONED_DOCS_DIR = exports.CURRENT_VERSION_NAME = void 0;
-// The name of the version at the root of your site (website/docs)
+/** The name of the version that's actively worked on (e.g. `website/docs`) */
 exports.CURRENT_VERSION_NAME = 'current';
+/** All doc versions are stored here by version names */
 exports.VERSIONED_DOCS_DIR = 'versioned_docs';
+/** All doc versioned sidebars are stored here by version names */
 exports.VERSIONED_SIDEBARS_DIR = 'versioned_sidebars';
+/** The version names. Should 1-1 map to the content of versioned docs dir. */
 exports.VERSIONS_JSON_FILE = 'versions.json';

package/lib/index.js

@@ -26,6 +26,8 @@ const utils_2 = require("./sidebars/utils");
 const categoryGeneratedIndex_1 = require("./categoryGeneratedIndex");
 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, versions_1.readVersionsMetadata)({ context, options });
     const pluginId = options.id;
     const pluginDataDirRoot = path_1.default.join(generatedFilesDir, 'docusaurus-plugin-content-docs');

package/lib/server-export.d.ts

@@ -5,4 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 export { CURRENT_VERSION_NAME, VERSIONED_DOCS_DIR, VERSIONED_SIDEBARS_DIR, VERSIONS_JSON_FILE, } from './constants';
-export { filterVersions, getDefaultVersionBanner, getVersionBadge, getVersionBanner, getVersionsFilePath, readVersionsFile, readVersionNames, } from './versions';
+export { filterVersions, getDefaultVersionBanner, getVersionBadge, getVersionBanner, } from './versions';
+export { readVersionNames } from './versions/files';

package/lib/server-export.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getVersionBanner = exports.getVersionBadge = exports.getDefaultVersionBanner = exports.filterVersions = exports.VERSIONS_JSON_FILE = exports.VERSIONED_SIDEBARS_DIR = exports.VERSIONED_DOCS_DIR = exports.CURRENT_VERSION_NAME = void 0;
+exports.readVersionNames = exports.getVersionBanner = exports.getVersionBadge = exports.getDefaultVersionBanner = exports.filterVersions = exports.VERSIONS_JSON_FILE = exports.VERSIONED_SIDEBARS_DIR = exports.VERSIONED_DOCS_DIR = exports.CURRENT_VERSION_NAME = void 0;
 // APIs available to Node.js
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "CURRENT_VERSION_NAME", { enumerable: true, get: function () { return constants_1.CURRENT_VERSION_NAME; } });
@@ -18,6 +18,5 @@ Object.defineProperty(exports, "filterVersions", { enumerable: true, get: functi
 Object.defineProperty(exports, "getDefaultVersionBanner", { enumerable: true, get: function () { return versions_1.getDefaultVersionBanner; } });
 Object.defineProperty(exports, "getVersionBadge", { enumerable: true, get: function () { return versions_1.getVersionBadge; } });
 Object.defineProperty(exports, "getVersionBanner", { enumerable: true, get: function () { return versions_1.getVersionBanner; } });
-Object.defineProperty(exports, "getVersionsFilePath", { enumerable: true, get: function () { return versions_1.getVersionsFilePath; } });
-Object.defineProperty(exports, "readVersionsFile", { enumerable: true, get: function () { return versions_1.readVersionsFile; } });
-Object.defineProperty(exports, "readVersionNames", { enumerable: true, get: function () { return versions_1.readVersionNames; } });
+var files_1 = require("./versions/files");
+Object.defineProperty(exports, "readVersionNames", { enumerable: true, get: function () { return files_1.readVersionNames; } });

package/lib/sidebars/index.js

@@ -30,7 +30,6 @@ exports.DefaultSidebars = {
 };
 exports.DisabledSidebars = {};
 // If a path is provided, make it absolute
-// use this before loadSidebars()
 function resolveSidebarPathOption(siteDir, sidebarPathOption) {
     return sidebarPathOption
         ? path_1.default.resolve(siteDir, sidebarPathOption)
@@ -76,7 +75,6 @@ async function loadSidebarsFileUnsafe(sidebarFilePath) {
     return (0, import_fresh_1.default)(sidebarFilePath);
 }
 exports.loadSidebarsFileUnsafe = loadSidebarsFileUnsafe;
-// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 async function loadSidebars(sidebarFilePath, options) {
     try {
         const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);

package/lib/versions/files.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 './index';
+/** `[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({ siteDir, locale, pluginId, versionName, }: {
+    siteDir: string;
+    locale: string;
+    pluginId: string;
+    versionName: string;
+}): string;
+/** `community` => `[siteDir]/community_versions.json` */
+export declare function getVersionsFilePath(siteDir: string, pluginId: string): string;
+/**
+ * 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,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.getVersionMetadataPaths = exports.readVersionNames = exports.getVersionsFilePath = exports.getDocsDirPathLocalized = exports.getVersionSidebarsPath = exports.getVersionDocsDirPath = void 0;
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const constants_1 = require("../constants");
+const validation_1 = require("./validation");
+const utils_1 = require("@docusaurus/utils");
+/** 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 path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_DOCS_DIR, pluginId), `version-${versionName}`);
+}
+exports.getVersionDocsDirPath = getVersionDocsDirPath;
+/** `[siteDir]/community_versioned_sidebars/version-1.0.0-sidebars.json` */
+function getVersionSidebarsPath(siteDir, pluginId, versionName) {
+    return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_SIDEBARS_DIR, pluginId), `version-${versionName}-sidebars.json`);
+}
+exports.getVersionSidebarsPath = getVersionSidebarsPath;
+function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
+    return (0, utils_1.getPluginI18nPath)({
+        siteDir,
+        locale,
+        pluginName: 'docusaurus-plugin-content-docs',
+        pluginId,
+        subPaths: [
+            versionName === constants_1.CURRENT_VERSION_NAME
+                ? constants_1.CURRENT_VERSION_NAME
+                : `version-${versionName}`,
+        ],
+    });
+}
+exports.getDocsDirPathLocalized = getDocsDirPathLocalized;
+/** `community` => `[siteDir]/community_versions.json` */
+function getVersionsFilePath(siteDir, pluginId) {
+    return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONS_JSON_FILE, pluginId));
+}
+exports.getVersionsFilePath = getVersionsFilePath;
+/**
+ * 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 fs_extra_1.default.pathExists(versionsFilePath)) {
+        const content = await fs_extra_1.default.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 ${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;
+}
+exports.readVersionNames = readVersionNames;
+/**
+ * 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 contentPathLocalized = getDocsDirPathLocalized({
+        siteDir: context.siteDir,
+        locale: context.i18n.currentLocale,
+        pluginId: options.id,
+        versionName,
+    });
+    const contentPath = isCurrent
+        ? 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 fs_extra_1.default.pathExists(contentPath))) {
+        throw new Error(`The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${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 fs_extra_1.default.pathExists(sidebarFilePath))) {
+        throw new Error(`The path to the sidebar file does not exist at "${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 };
+}
+exports.getVersionMetadataPaths = getVersionMetadataPaths;

package/lib/versions/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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, VersionBanner, VersionMetadata } from '@docusaurus/plugin-content-docs';
+import type { LoadContext } from '@docusaurus/types';
+export declare type VersionContext = {
+    /** The version name to get banner of. */
+    versionName: string;
+    /** All versions, ordered from newest to oldest. */
+    versionNames: string[];
+    lastVersionName: string;
+    context: LoadContext;
+    options: PluginOptions;
+};
+/**
+ * The default version banner depends on the version's relative position to the
+ * latest version. More recent ones are "unreleased", and older ones are
+ * "unmaintained".
+ */
+export declare function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }: VersionContext): VersionBanner | null;
+export declare function getVersionBanner(context: VersionContext): VersionMetadata['banner'];
+export declare function getVersionBadge({ versionName, versionNames, options, }: VersionContext): VersionMetadata['badge'];
+/**
+ * Filter versions according to provided options (i.e. `onlyIncludeVersions`).
+ *
+ * Note: we preserve the order in which versions are provided; the order of the
+ * `onlyIncludeVersions` array does not matter
+ */
+export declare function filterVersions(versionNamesUnfiltered: string[], options: PluginOptions): string[];
+export declare function readVersionsMetadata({ context, options, }: {
+    context: LoadContext;
+    options: PluginOptions;
+}): Promise<VersionMetadata[]>;

package/lib/versions/index.js

@@ -0,0 +1,155 @@
+"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.readVersionsMetadata = exports.filterVersions = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+const constants_1 = require("../constants");
+const utils_1 = require("@docusaurus/utils");
+const validation_1 = require("./validation");
+const files_1 = require("./files");
+function getVersionEditUrls({ contentPath, contentPathLocalized, context, options, }) {
+    // If the user is using the functional form of editUrl,
+    // she has total freedom and we can't compute a "version edit url"
+    if (!options.editUrl || typeof options.editUrl === 'function') {
+        return { editUrl: undefined, editUrlLocalized: undefined };
+    }
+    const editDirPath = options.editCurrentVersion ? options.path : contentPath;
+    const editDirPathLocalized = options.editCurrentVersion
+        ? (0, files_1.getDocsDirPathLocalized)({
+            siteDir: context.siteDir,
+            locale: context.i18n.currentLocale,
+            versionName: constants_1.CURRENT_VERSION_NAME,
+            pluginId: options.id,
+        })
+        : contentPathLocalized;
+    const versionPathSegment = (0, utils_1.posixPath)(path_1.default.relative(context.siteDir, path_1.default.resolve(context.siteDir, editDirPath)));
+    const versionPathSegmentLocalized = (0, utils_1.posixPath)(path_1.default.relative(context.siteDir, path_1.default.resolve(context.siteDir, editDirPathLocalized)));
+    const editUrl = (0, utils_1.normalizeUrl)([options.editUrl, versionPathSegment]);
+    const editUrlLocalized = (0, utils_1.normalizeUrl)([
+        options.editUrl,
+        versionPathSegmentLocalized,
+    ]);
+    return { editUrl, editUrlLocalized };
+}
+/**
+ * The default version banner depends on the version's relative position to the
+ * latest version. More recent ones are "unreleased", and older ones are
+ * "unmaintained".
+ */
+function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }) {
+    // Current version: good, no banner
+    if (versionName === lastVersionName) {
+        return null;
+    }
+    // Upcoming versions: unreleased banner
+    if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
+        return 'unreleased';
+    }
+    // Older versions: display unmaintained banner
+    return 'unmaintained';
+}
+exports.getDefaultVersionBanner = getDefaultVersionBanner;
+function getVersionBanner(context) {
+    const { versionName, options } = context;
+    const versionBannerOption = options.versions[versionName]?.banner;
+    if (versionBannerOption) {
+        return versionBannerOption === 'none' ? null : versionBannerOption;
+    }
+    return getDefaultVersionBanner(context);
+}
+exports.getVersionBanner = getVersionBanner;
+function getVersionBadge({ versionName, versionNames, options, }) {
+    // If site is not versioned or only one version is included
+    // we don't show the version badge by default
+    // See https://github.com/facebook/docusaurus/issues/3362
+    const defaultVersionBadge = versionNames.length !== 1;
+    return options.versions[versionName]?.badge ?? defaultVersionBadge;
+}
+exports.getVersionBadge = getVersionBadge;
+function getVersionClassName({ versionName, options, }) {
+    const defaultVersionClassName = `docs-version-${versionName}`;
+    return options.versions[versionName]?.className ?? defaultVersionClassName;
+}
+function getVersionLabel({ versionName, options, }) {
+    const defaultVersionLabel = versionName === constants_1.CURRENT_VERSION_NAME ? 'Next' : versionName;
+    return options.versions[versionName]?.label ?? defaultVersionLabel;
+}
+function getVersionPathPart({ versionName, options, lastVersionName, }) {
+    function getDefaultVersionPathPart() {
+        if (versionName === lastVersionName) {
+            return '';
+        }
+        return versionName === constants_1.CURRENT_VERSION_NAME ? 'next' : versionName;
+    }
+    return options.versions[versionName]?.path ?? getDefaultVersionPathPart();
+}
+async function createVersionMetadata(context) {
+    const { versionName, lastVersionName, options, context: loadContext } = context;
+    const { sidebarFilePath, contentPath, contentPathLocalized } = await (0, files_1.getVersionMetadataPaths)(context);
+    const versionPathPart = getVersionPathPart(context);
+    const routePath = (0, utils_1.normalizeUrl)([
+        loadContext.baseUrl,
+        options.routeBasePath,
+        versionPathPart,
+    ]);
+    const versionEditUrls = getVersionEditUrls({
+        contentPath,
+        contentPathLocalized,
+        context: loadContext,
+        options,
+    });
+    return {
+        versionName,
+        label: getVersionLabel(context),
+        banner: getVersionBanner(context),
+        badge: getVersionBadge(context),
+        className: getVersionClassName(context),
+        path: routePath,
+        tagsPath: (0, utils_1.normalizeUrl)([routePath, options.tagsBasePath]),
+        ...versionEditUrls,
+        isLast: versionName === lastVersionName,
+        routePriority: versionPathPart === '' ? -1 : undefined,
+        sidebarFilePath,
+        contentPath,
+        contentPathLocalized,
+    };
+}
+/**
+ * Filter versions according to provided options (i.e. `onlyIncludeVersions`).
+ *
+ * Note: we preserve the order in which versions are provided; the order of the
+ * `onlyIncludeVersions` array does not matter
+ */
+function filterVersions(versionNamesUnfiltered, options) {
+    if (options.onlyIncludeVersions) {
+        return versionNamesUnfiltered.filter((name) => options.onlyIncludeVersions.includes(name));
+    }
+    return versionNamesUnfiltered;
+}
+exports.filterVersions = filterVersions;
+function getLastVersionName({ versionNames, options, }) {
+    return (options.lastVersion ??
+        versionNames.find((name) => name !== constants_1.CURRENT_VERSION_NAME) ??
+        constants_1.CURRENT_VERSION_NAME);
+}
+async function readVersionsMetadata({ context, options, }) {
+    const allVersionNames = await (0, files_1.readVersionNames)(context.siteDir, options);
+    (0, validation_1.validateVersionsOptions)(allVersionNames, options);
+    const versionNames = filterVersions(allVersionNames, options);
+    const lastVersionName = getLastVersionName({ versionNames, options });
+    const versionsMetadata = await Promise.all(versionNames.map((versionName) => createVersionMetadata({
+        versionName,
+        versionNames,
+        lastVersionName,
+        context,
+        options,
+    })));
+    return versionsMetadata;
+}
+exports.readVersionsMetadata = readVersionsMetadata;

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;

package/lib/versions/validation.js

@@ -0,0 +1,71 @@
+"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.validateVersionsOptions = exports.validateVersionNames = exports.validateVersionName = void 0;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+function validateVersionName(name) {
+    if (typeof name !== 'string') {
+        throw new Error(`Versions should be strings. Found type "${typeof name}" for version "${name}".`);
+    }
+    if (!name.trim()) {
+        throw new Error(`Invalid version name "${name}": version name must contain at least one non-whitespace character.`);
+    }
+    const errors = [
+        [/[/\\]/, 'should not include slash (/) or backslash (\\)'],
+        [/.{33,}/, 'cannot be longer than 32 characters'],
+        // eslint-disable-next-line no-control-regex
+        [/[<>:"|?*\x00-\x1F]/, 'should be a valid file path'],
+        [/^\.\.?$/, 'should not be "." or ".."'],
+    ];
+    errors.forEach(([pattern, message]) => {
+        if (pattern.test(name)) {
+            throw new Error(`Invalid version name "${name}": version name ${message}.`);
+        }
+    });
+}
+exports.validateVersionName = validateVersionName;
+function validateVersionNames(names) {
+    if (!Array.isArray(names)) {
+        throw new Error(`The versions file should contain an array of version names! Found content: ${JSON.stringify(names)}`);
+    }
+    names.forEach(validateVersionName);
+}
+exports.validateVersionNames = validateVersionNames;
+/**
+ * @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)
+ */
+function validateVersionsOptions(availableVersionNames, options) {
+    const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(', ')}`;
+    if (options.lastVersion &&
+        !availableVersionNames.includes(options.lastVersion)) {
+        throw new Error(`Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`);
+    }
+    const unknownVersionConfigNames = lodash_1.default.difference(Object.keys(options.versions), availableVersionNames);
+    if (unknownVersionConfigNames.length > 0) {
+        throw new Error(`Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(',')}) found. ${availableVersionNamesMsg}`);
+    }
+    if (options.onlyIncludeVersions) {
+        if (options.onlyIncludeVersions.length === 0) {
+            throw new Error(`Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`);
+        }
+        const unknownOnlyIncludeVersionNames = lodash_1.default.difference(options.onlyIncludeVersions, availableVersionNames);
+        if (unknownOnlyIncludeVersionNames.length > 0) {
+            throw new Error(`Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(',')}) found. ${availableVersionNamesMsg}`);
+        }
+        if (options.lastVersion &&
+            !options.onlyIncludeVersions.includes(options.lastVersion)) {
+            throw new Error(`Invalid docs option "lastVersion": if you use both the "onlyIncludeVersions" and "lastVersion" options, then "lastVersion" must be present in the provided "onlyIncludeVersions" array.`);
+        }
+    }
+}
+exports.validateVersionsOptions = validateVersionsOptions;