@docusaurus/plugin-content-docs 2.0.0-beta.138b4c997 → 2.0.0-beta.14

package/lib/versions.js

@@ -8,16 +8,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDocsDirPaths = exports.readVersionsMetadata = exports.getVersionsFilePath = exports.getVersionedSidebarsDirPath = exports.getVersionedDocsDirPath = 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 path_1 = (0, tslib_1.__importDefault)(require("path"));
+const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
 const constants_1 = require("./constants");
-const constants_2 = require("@docusaurus/core/lib/constants");
 const utils_1 = require("@docusaurus/utils");
 const lodash_1 = require("lodash");
 const sidebars_1 = require("./sidebars");
 // retro-compatibility: no prefix for the default plugin id
 function addPluginIdPrefix(fileOrDir, pluginId) {
-    if (pluginId === constants_2.DEFAULT_PLUGIN_ID) {
+    if (pluginId === utils_1.DEFAULT_PLUGIN_ID) {
         return fileOrDir;
     }
     else {
@@ -83,7 +82,7 @@ function readVersionNames(siteDir, options) {
     return versions;
 }
 function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
-    return utils_1.getPluginI18nPath({
+    return (0, utils_1.getPluginI18nPath)({
         siteDir,
         locale,
         pluginName: 'docusaurus-plugin-content-docs',
@@ -108,7 +107,7 @@ function getVersionMetadataPaths({ versionName, context, options, }) {
     });
     function getSidebarFilePath() {
         if (isCurrentVersion) {
-            return sidebars_1.resolveSidebarPathOption(context.siteDir, options.sidebarPath);
+            return (0, sidebars_1.resolveSidebarPathOption)(context.siteDir, options.sidebarPath);
         }
         else {
             return path_1.default.join(getVersionedSidebarsDirPath(context.siteDir, options.id), `version-${versionName}-sidebars.json`);
@@ -138,10 +137,10 @@ function getVersionEditUrls({ contentPath, contentPathLocalized, context: { site
             pluginId: id,
         })
         : contentPathLocalized;
-    const versionPathSegment = utils_1.posixPath(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPath)));
-    const versionPathSegmentLocalized = utils_1.posixPath(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPathLocalized)));
-    const versionEditUrl = utils_1.normalizeUrl([editUrl, versionPathSegment]);
-    const versionEditUrlLocalized = utils_1.normalizeUrl([
+    const versionPathSegment = (0, utils_1.posixPath)(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPath)));
+    const versionPathSegmentLocalized = (0, utils_1.posixPath)(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPathLocalized)));
+    const versionEditUrl = (0, utils_1.normalizeUrl)([editUrl, versionPathSegment]);
+    const versionEditUrlLocalized = (0, utils_1.normalizeUrl)([
         editUrl,
         versionPathSegmentLocalized,
     ]);
@@ -153,7 +152,7 @@ function getVersionEditUrls({ contentPath, contentPathLocalized, context: { site
 function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }) {
     // Current version: good, no banner
     if (versionName === lastVersionName) {
-        return 'none';
+        return null;
     }
     // Upcoming versions: unreleased banner
     else if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
@@ -166,20 +165,34 @@ function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }
 }
 function getVersionBanner({ versionName, versionNames, lastVersionName, options, }) {
     var _a;
-    const versionOptionBanner = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.banner;
-    return (versionOptionBanner !== null && versionOptionBanner !== void 0 ? versionOptionBanner : getDefaultVersionBanner({
+    const versionBannerOption = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.banner;
+    if (versionBannerOption) {
+        return versionBannerOption === 'none' ? null : versionBannerOption;
+    }
+    return getDefaultVersionBanner({
         versionName,
         versionNames,
         lastVersionName,
-    }));
+    });
+}
+function getVersionBadge({ versionName, versionNames, options, }) {
+    var _a;
+    const versionBadgeOption = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.badge;
+    // 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 versionBadgeDefault = versionNames.length !== 1;
+    return versionBadgeOption !== null && versionBadgeOption !== void 0 ? versionBadgeOption : versionBadgeDefault;
+}
+function getVersionClassName({ versionName, options, }) {
+    var _a;
+    const versionClassNameOption = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.className;
+    const versionClassNameDefault = `docs-version-${versionName}`;
+    return versionClassNameOption !== null && versionClassNameOption !== void 0 ? versionClassNameOption : versionClassNameDefault;
 }
 function createVersionMetadata({ versionName, versionNames, lastVersionName, context, options, }) {
     var _a, _b, _c;
-    const { sidebarFilePath, contentPath, contentPathLocalized, } = getVersionMetadataPaths({
-        versionName,
-        context,
-        options,
-    });
+    const { sidebarFilePath, contentPath, contentPathLocalized } = getVersionMetadataPaths({ versionName, context, options });
     const isLast = versionName === lastVersionName;
     // retro-compatible values
     const defaultVersionLabel = versionName === constants_1.CURRENT_VERSION_NAME ? 'Next' : versionName;
@@ -193,7 +206,7 @@ function createVersionMetadata({ versionName, versionNames, lastVersionName, con
     const versionOptions = (_a = options.versions[versionName]) !== null && _a !== void 0 ? _a : {};
     const versionLabel = (_b = versionOptions.label) !== null && _b !== void 0 ? _b : defaultVersionLabel;
     const versionPathPart = (_c = versionOptions.path) !== null && _c !== void 0 ? _c : defaultVersionPathPart;
-    const versionPath = utils_1.normalizeUrl([
+    const versionPath = (0, utils_1.normalizeUrl)([
         context.baseUrl,
         options.routeBasePath,
         versionPathPart,
@@ -206,10 +219,14 @@ function createVersionMetadata({ versionName, versionNames, lastVersionName, con
     });
     // Because /docs/:route` should always be after `/docs/versionName/:route`.
     const routePriority = versionPathPart === '' ? -1 : undefined;
+    // the path that will be used to refer the docs tags
+    // example below will be using /docs/tags
+    const tagsPath = (0, utils_1.normalizeUrl)([versionPath, options.tagsBasePath]);
     return {
         versionName,
         versionLabel,
         versionPath,
+        tagsPath,
         versionEditUrl: versionEditUrls === null || versionEditUrls === void 0 ? void 0 : versionEditUrls.versionEditUrl,
         versionEditUrlLocalized: versionEditUrls === null || versionEditUrls === void 0 ? void 0 : versionEditUrls.versionEditUrlLocalized,
         versionBanner: getVersionBanner({
@@ -218,6 +235,8 @@ function createVersionMetadata({ versionName, versionNames, lastVersionName, con
             lastVersionName,
             options,
         }),
+        versionBadge: getVersionBadge({ versionName, versionNames, options }),
+        versionClassName: getVersionClassName({ versionName, options }),
         isLast,
         routePriority,
         sidebarFilePath,
@@ -263,7 +282,7 @@ function checkVersionsOptions(availableVersionNames, options) {
         !availableVersionNames.includes(options.lastVersion)) {
         throw new Error(`Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`);
     }
-    const unknownVersionConfigNames = lodash_1.difference(Object.keys(options.versions), availableVersionNames);
+    const unknownVersionConfigNames = (0, lodash_1.difference)(Object.keys(options.versions), availableVersionNames);
     if (unknownVersionConfigNames.length > 0) {
         throw new Error(`Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(',')}) found. ${availableVersionNamesMsg}`);
     }
@@ -271,7 +290,7 @@ function checkVersionsOptions(availableVersionNames, options) {
         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.difference(options.onlyIncludeVersions, availableVersionNames);
+        const unknownOnlyIncludeVersionNames = (0, lodash_1.difference)(options.onlyIncludeVersions, availableVersionNames);
         if (unknownOnlyIncludeVersionNames.length > 0) {
             throw new Error(`Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(',')}) found. ${availableVersionNamesMsg}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "2.0.0-beta.138b4c997",
+  "version": "2.0.0-beta.14",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-docs.d.ts",
@@ -17,41 +17,41 @@
     "directory": "packages/docusaurus-plugin-content-docs"
   },
   "license": "MIT",
-  "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.138b4c997",
-    "@types/js-yaml": "^4.0.0",
-    "@types/picomatch": "^2.2.1",
-    "commander": "^5.1.0",
-    "picomatch": "^2.1.1"
-  },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.138b4c997",
-    "@docusaurus/mdx-loader": "2.0.0-beta.138b4c997",
-    "@docusaurus/types": "2.0.0-beta.138b4c997",
-    "@docusaurus/utils": "2.0.0-beta.138b4c997",
-    "@docusaurus/utils-validation": "2.0.0-beta.138b4c997",
-    "chalk": "^4.1.1",
+    "@docusaurus/core": "2.0.0-beta.14",
+    "@docusaurus/logger": "2.0.0-beta.14",
+    "@docusaurus/mdx-loader": "2.0.0-beta.14",
+    "@docusaurus/utils": "2.0.0-beta.14",
+    "@docusaurus/utils-validation": "2.0.0-beta.14",
     "combine-promises": "^1.1.0",
     "escape-string-regexp": "^4.0.0",
-    "execa": "^5.0.0",
     "fs-extra": "^10.0.0",
     "globby": "^11.0.2",
     "import-fresh": "^3.2.2",
     "js-yaml": "^4.0.0",
-    "loader-utils": "^1.2.3",
+    "loader-utils": "^2.0.0",
     "lodash": "^4.17.20",
     "remark-admonitions": "^1.2.1",
     "shelljs": "^0.8.4",
-    "tslib": "^2.2.0",
+    "tslib": "^2.3.1",
     "utility-types": "^3.10.0",
-    "webpack": "^5.40.0"
+    "webpack": "^5.61.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "2.0.0-beta.14",
+    "@docusaurus/types": "2.0.0-beta.14",
+    "@types/js-yaml": "^4.0.0",
+    "@types/picomatch": "^2.2.1",
+    "commander": "^5.1.0",
+    "picomatch": "^2.1.1",
+    "utility-types": "^3.10.0"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "8cc620648710971acc459aabd2c6f505ef757701"
+  "gitHead": "c4824a8937d8f1aa0806667749cbc74058e2b294"
 }

package/src/categoryGeneratedIndex.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 {CategoryGeneratedIndexMetadata, DocMetadataBase} from './types';
+import {SidebarItemCategoryWithGeneratedIndex} from './sidebars/types';
+import {SidebarsUtils, toNavigationLink} from './sidebars/utils';
+import {createDocsByIdIndex} from './docs';
+
+function getCategoryGeneratedIndexMetadata({
+  category,
+  sidebarsUtils,
+  docsById,
+}: {
+  category: SidebarItemCategoryWithGeneratedIndex;
+  sidebarsUtils: SidebarsUtils;
+  docsById: Record<string, DocMetadataBase>;
+}): CategoryGeneratedIndexMetadata {
+  const {sidebarName, previous, next} =
+    sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
+  if (!sidebarName) {
+    throw new Error('unexpected');
+  }
+
+  return {
+    title: category.link.title ?? category.label,
+    description: category.link.description,
+    slug: category.link.slug,
+    permalink: category.link.permalink,
+    sidebar: sidebarName,
+    previous: toNavigationLink(previous, docsById),
+    next: toNavigationLink(next, docsById),
+  };
+}
+
+export function getCategoryGeneratedIndexMetadataList({
+  docs,
+  sidebarsUtils,
+}: {
+  sidebarsUtils: SidebarsUtils;
+  docs: DocMetadataBase[];
+}): CategoryGeneratedIndexMetadata[] {
+  const docsById = createDocsByIdIndex(docs);
+
+  const categoryGeneratedIndexItems =
+    sidebarsUtils.getCategoryGeneratedIndexList();
+  return categoryGeneratedIndexItems.map((category) =>
+    getCategoryGeneratedIndexMetadata({
+      category,
+      sidebarsUtils,
+      docsById,
+    }),
+  );
+}

package/src/cli.ts

@@ -12,13 +12,10 @@ import {
 } from './versions';
 import fs from 'fs-extra';
 import path from 'path';
-import {
-  PathOptions,
-  UnprocessedSidebarItem,
-  UnprocessedSidebars,
-} from './types';
-import {loadSidebars, resolveSidebarPathOption} from './sidebars';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
+import type {PathOptions, SidebarOptions} from './types';
+import {loadSidebarsFile, resolveSidebarPathOption} from './sidebars';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
 
 function createVersionedSidebarFile({
   siteDir,
@@ -32,41 +29,13 @@ function createVersionedSidebarFile({
   version: string;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  const loadedSidebars = loadSidebars(sidebarPath);
+  // Note: we don't need the sidebars file to be normalized: it's ok to let plugin option changes to impact older, versioned sidebars
+  const sidebars = loadSidebarsFile(sidebarPath);
 
   // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
-  const shouldCreateVersionedSidebarFile =
-    Object.keys(loadedSidebars).length > 0;
+  const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
 
   if (shouldCreateVersionedSidebarFile) {
-    // TODO @slorber: this "version prefix" in versioned sidebars looks like a bad idea to me
-    // TODO try to get rid of it
-    // Transform id in original sidebar to versioned id.
-    const normalizeItem = (
-      item: UnprocessedSidebarItem,
-    ): UnprocessedSidebarItem => {
-      switch (item.type) {
-        case 'category':
-          return {...item, items: item.items.map(normalizeItem)};
-        case 'ref':
-        case 'doc':
-          return {
-            type: item.type,
-            id: `version-${version}/${item.id}`,
-          };
-        default:
-          return item;
-      }
-    };
-
-    const versionedSidebar: UnprocessedSidebars = Object.entries(
-      loadedSidebars,
-    ).reduce((acc: UnprocessedSidebars, [sidebarId, sidebarItems]) => {
-      const newVersionedSidebarId = `version-${version}/${sidebarId}`;
-      acc[newVersionedSidebarId] = sidebarItems.map(normalizeItem);
-      return acc;
-    }, {});
-
     const versionedSidebarsDir = getVersionedSidebarsDirPath(siteDir, pluginId);
     const newSidebarFile = path.join(
       versionedSidebarsDir,
@@ -75,19 +44,18 @@ function createVersionedSidebarFile({
     fs.ensureDirSync(path.dirname(newSidebarFile));
     fs.writeFileSync(
       newSidebarFile,
-      `${JSON.stringify(versionedSidebar, null, 2)}\n`,
+      `${JSON.stringify(sidebars, null, 2)}\n`,
       'utf8',
     );
   }
 }
 
 // Tests depend on non-default export for mocking.
-// eslint-disable-next-line import/prefer-default-export
 export function cliDocsVersionCommand(
   version: string | null | undefined,
   siteDir: string,
   pluginId: string,
-  options: PathOptions,
+  options: PathOptions & SidebarOptions,
 ): void {
   // It wouldn't be very user-friendly to show a [default] log prefix,
   // so we use [docs] instead of [default]
@@ -166,5 +134,5 @@ export function cliDocsVersionCommand(
   fs.ensureDirSync(path.dirname(versionsJSONFile));
   fs.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
 
-  console.log(`${pluginIdLogPrefix}: version ${version} created!`);
+  logger.success`name=${pluginIdLogPrefix}: version name=${version} created!`;
 }

package/src/client/docsClientUtils.ts

@@ -20,35 +20,23 @@ export type ActivePlugin = {
   pluginData: GlobalPluginData;
 };
 
-export type GetActivePluginOptions = {failfast?: boolean};
+export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active
 
 // get the data of the plugin that is currently "active"
 // ie the docs of that plugin are currently browsed
 // it is useful to support multiple docs plugin instances
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options: {failfast: true}, // use fail-fast option if you know for sure one plugin instance is active
-): ActivePlugin;
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options?: GetActivePluginOptions,
-): ActivePlugin | undefined;
-
 export function getActivePlugin(
   allPluginDatas: Record<string, GlobalPluginData>,
   pathname: string,
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined {
   const activeEntry = Object.entries(allPluginDatas).find(
-    ([_id, pluginData]) => {
-      return !!matchPath(pathname, {
+    ([_id, pluginData]) =>
+      !!matchPath(pathname, {
         path: pluginData.path,
         exact: false,
         strict: false,
-      });
-    },
+      }),
   );
 
   const activePlugin: ActivePlugin | undefined = activeEntry
@@ -74,9 +62,8 @@ export type ActiveDocContext = {
   alternateDocVersions: Record<string, Doc>;
 };
 
-export const getLatestVersion = (data: GlobalPluginData): Version => {
-  return data.versions.find((version) => version.isLast)!;
-};
+export const getLatestVersion = (data: GlobalPluginData): Version =>
+  data.versions.find((version) => version.isLast)!;
 
 // Note: return undefined on doc-unrelated pages,
 // because there's no version currently considered as active
@@ -91,13 +78,14 @@ export const getActiveVersion = (
     ...data.versions.filter((version) => version !== lastVersion),
     lastVersion,
   ];
-  return orderedVersionsMetadata.find((version) => {
-    return !!matchPath(pathname, {
-      path: version.path,
-      exact: false,
-      strict: false,
-    });
-  });
+  return orderedVersionsMetadata.find(
+    (version) =>
+      !!matchPath(pathname, {
+        path: version.path,
+        exact: false,
+        strict: false,
+      }),
+  );
 };
 
 export const getActiveDocContext = (

package/src/docFrontMatter.ts

@@ -5,17 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
   URISchema,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
-import {DocFrontMatter} from './types';
+import type {DocFrontMatter} from './types';
 
 // NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
+// We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
 const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
@@ -28,10 +28,15 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   description: Joi.string().allow(''), // see  https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   slug: Joi.string(),
   sidebar_label: Joi.string(),
-  sidebar_position: Joi.number().min(0),
+  sidebar_position: Joi.number(),
+  sidebar_class_name: Joi.string(),
+  tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),
   custom_edit_url: URISchema.allow('', null),
   parse_number_prefixes: Joi.boolean(),
+  pagination_next: Joi.string().allow(null),
+  pagination_prev: Joi.string().allow(null),
+  ...FrontMatterTOCHeadingLevels,
 }).unknown();
 
 export function validateDocFrontMatter(