@docusaurus/plugin-content-docs 2.4.1 → 3.0.0-beta.0

package/lib/translations.js

@@ -20,16 +20,6 @@ function getVersionFileName(versionName) {
     // but it's for consistency with site/versioned_docs
     return `version-${versionName}`;
 }
-// TODO legacy, the sidebar name is like "version-2.0.0-alpha.66/docs"
-// input: "version-2.0.0-alpha.66/docs"
-// output: "docs"
-function getNormalizedSidebarName({ versionName, sidebarName, }) {
-    if (versionName === constants_1.CURRENT_VERSION_NAME || !sidebarName.includes('/')) {
-        return sidebarName;
-    }
-    const [, ...rest] = sidebarName.split('/');
-    return rest.join('/');
-}
 function getSidebarTranslationFileContent(sidebar, sidebarName) {
     const categories = (0, utils_2.collectSidebarCategories)(sidebar);
     const categoryContent = Object.fromEntries(categories.flatMap((category) => {
@@ -127,21 +117,12 @@ function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
     });
 }
 function getSidebarsTranslations(version) {
-    return (0, utils_1.mergeTranslations)(Object.entries(version.sidebars).map(([sidebarName, sidebar]) => {
-        const normalizedSidebarName = getNormalizedSidebarName({
-            sidebarName,
-            versionName: version.versionName,
-        });
-        return getSidebarTranslationFileContent(sidebar, normalizedSidebarName);
-    }));
+    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: getNormalizedSidebarName({
-            sidebarName,
-            versionName: version.versionName,
-        }),
+        sidebarName,
         sidebarsTranslations,
     }));
 }

package/lib/types.d.ts

@@ -7,28 +7,29 @@
 import type { BrokenMarkdownLink, Tag } from '@docusaurus/utils';
 import type { VersionMetadata, LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
 import type { SidebarsUtils } from './sidebars/utils';
-export declare type DocFile = {
+export type DocFile = {
     contentPath: string;
     filePath: string;
     source: string;
     content: string;
 };
-export declare type SourceToPermalink = {
+export type SourceToPermalink = {
     [source: string]: string;
 };
-export declare type VersionTag = Tag & {
+export type VersionTag = Tag & {
     /** All doc ids having this tag. */
     docIds: string[];
+    unlisted: boolean;
 };
-export declare type VersionTags = {
+export type VersionTags = {
     [permalink: string]: VersionTag;
 };
-export declare type FullVersion = LoadedVersion & {
+export type FullVersion = LoadedVersion & {
     sidebarsUtils: SidebarsUtils;
     categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
-export declare type DocBrokenMarkdownLink = BrokenMarkdownLink<VersionMetadata>;
-export declare type DocsMarkdownOption = {
+export type DocBrokenMarkdownLink = BrokenMarkdownLink<VersionMetadata>;
+export type DocsMarkdownOption = {
     versionsMetadata: VersionMetadata[];
     siteDir: string;
     sourceToPermalink: SourceToPermalink;

package/lib/versions/index.d.ts

@@ -4,9 +4,10 @@
  * 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 { FullVersion } from '../types';
 import type { LoadContext } from '@docusaurus/types';
-export declare type VersionContext = {
+import type { LoadedVersion, PluginOptions, VersionBanner, VersionMetadata } from '@docusaurus/plugin-content-docs';
+export type VersionContext = {
     /** The version name to get banner of. */
     versionName: string;
     /** All versions, ordered from newest to oldest. */
@@ -35,3 +36,4 @@ export declare function readVersionsMetadata({ context, options, }: {
     context: LoadContext;
     options: PluginOptions;
 }): Promise<VersionMetadata[]>;
+export declare function toFullVersion(version: LoadedVersion): FullVersion;

package/lib/versions/index.js

@@ -6,13 +6,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readVersionsMetadata = exports.filterVersions = exports.getVersionNoIndex = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
+exports.toFullVersion = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionNoIndex = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
 const constants_1 = require("../constants");
 const validation_1 = require("./validation");
 const files_1 = require("./files");
+const utils_2 = require("../sidebars/utils");
+const categoryGeneratedIndex_1 = require("../categoryGeneratedIndex");
 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"
@@ -157,3 +159,15 @@ async function readVersionsMetadata({ context, options, }) {
     return versionsMetadata;
 }
 exports.readVersionsMetadata = readVersionsMetadata;
+function toFullVersion(version) {
+    const sidebarsUtils = (0, utils_2.createSidebarsUtils)(version.sidebars);
+    return {
+        ...version,
+        sidebarsUtils,
+        categoryGeneratedIndices: (0, categoryGeneratedIndex_1.getCategoryGeneratedIndexMetadataList)({
+            docs: version.docs,
+            sidebarsUtils,
+        }),
+    };
+}
+exports.toFullVersion = toFullVersion;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "2.4.1",
+  "version": "3.0.0-beta.0",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,22 +35,22 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.4.1",
-    "@docusaurus/logger": "2.4.1",
-    "@docusaurus/mdx-loader": "2.4.1",
-    "@docusaurus/module-type-aliases": "2.4.1",
-    "@docusaurus/types": "2.4.1",
-    "@docusaurus/utils": "2.4.1",
-    "@docusaurus/utils-validation": "2.4.1",
-    "@types/react-router-config": "^5.0.6",
+    "@docusaurus/core": "3.0.0-beta.0",
+    "@docusaurus/logger": "3.0.0-beta.0",
+    "@docusaurus/mdx-loader": "3.0.0-beta.0",
+    "@docusaurus/module-type-aliases": "3.0.0-beta.0",
+    "@docusaurus/types": "3.0.0-beta.0",
+    "@docusaurus/utils": "3.0.0-beta.0",
+    "@docusaurus/utils-validation": "3.0.0-beta.0",
+    "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
-    "fs-extra": "^10.1.0",
+    "fs-extra": "^11.1.1",
     "import-fresh": "^3.3.0",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
-    "tslib": "^2.4.0",
+    "tslib": "^2.6.0",
     "utility-types": "^3.10.0",
-    "webpack": "^5.73.0"
+    "webpack": "^5.88.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.5",
@@ -60,11 +60,11 @@
     "shelljs": "^0.8.5"
   },
   "peerDependencies": {
-    "react": "^16.8.4 || ^17.0.0",
-    "react-dom": "^16.8.4 || ^17.0.0"
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
   },
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "60e657d8ae5a4a9ed1c2d777f9defd882cc12681"
+  "gitHead": "27a1e90d9fff88af90ecad35bea16d4d7230482a"
 }

package/src/client/index.ts

@@ -37,7 +37,8 @@ export type GlobalDoc = {
    */
   id: string;
   path: string;
-  sidebar: string | undefined;
+  sidebar?: string;
+  unlisted?: boolean;
 };
 
 export type GlobalVersion = {

package/src/docs.ts

@@ -7,6 +7,7 @@
 
 import path from 'path';
 import fs from 'fs-extra';
+import _ from 'lodash';
 import logger from '@docusaurus/logger';
 import {
   aliasedSitePath,
@@ -18,11 +19,12 @@ import {
   posixPath,
   Globby,
   normalizeFrontMatterTags,
+  isUnlisted,
+  isDraft,
 } from '@docusaurus/utils';
 
 import {getFileLastUpdate} from './lastUpdate';
 import getSlug from './slug';
-import {CURRENT_VERSION_NAME} from './constants';
 import {stripPathNumberPrefixes} from './numberPrefix';
 import {validateDocFrontMatter} from './frontMatter';
 import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
@@ -35,7 +37,6 @@ import type {
   PropNavigationLink,
   LastUpdateData,
   VersionMetadata,
-  DocFrontMatter,
   LoadedVersion,
   FileChange,
 } from '@docusaurus/plugin-content-docs';
@@ -125,17 +126,6 @@ export async function readVersionDocs(
 
 export type DocEnv = 'production' | 'development';
 
-/** Docs with draft front matter are only considered draft in production. */
-function isDraftForEnvironment({
-  env,
-  frontMatter,
-}: {
-  frontMatter: DocFrontMatter;
-  env: DocEnv;
-}): boolean {
-  return (env === 'production' && frontMatter.draft) ?? false;
-}
-
 async function doProcessDocMetadata({
   docFile,
   versionMetadata,
@@ -198,14 +188,6 @@ async function doProcessDocMetadata({
   const sidebarPosition: number | undefined =
     frontMatter.sidebar_position ?? numberPrefix;
 
-  // TODO legacy retrocompatibility
-  // The same doc in 2 distinct version could keep the same id,
-  // we just need to namespace the data by version
-  const versionIdPrefix =
-    versionMetadata.versionName === CURRENT_VERSION_NAME
-      ? undefined
-      : `version-${versionMetadata.versionName}`;
-
   // TODO legacy retrocompatibility
   // I think it's bad to affect the front matter id with the dirname?
   function computeDirNameIdPrefix() {
@@ -218,13 +200,7 @@ async function doProcessDocMetadata({
       : sourceDirName;
   }
 
-  const unversionedId = [computeDirNameIdPrefix(), baseID]
-    .filter(Boolean)
-    .join('/');
-
-  // TODO is versioning the id very useful in practice?
-  // legacy versioned id, requires a breaking change to modify this
-  const id = [versionIdPrefix, unversionedId].filter(Boolean).join('/');
+  const id = [computeDirNameIdPrefix(), baseID].filter(Boolean).join('/');
 
   const docSlug = getSlug({
     baseID,
@@ -268,7 +244,8 @@ async function doProcessDocMetadata({
     return undefined;
   }
 
-  const draft = isDraftForEnvironment({env, frontMatter});
+  const draft = isDraft({env, frontMatter});
+  const unlisted = isUnlisted({env, frontMatter});
 
   const formatDate = (locale: string, date: Date, calendar: string): string => {
     try {
@@ -290,7 +267,6 @@ async function doProcessDocMetadata({
   // Adding properties to object after instantiation will cause hidden
   // class transitions.
   return {
-    unversionedId,
     id,
     title,
     description,
@@ -299,6 +275,7 @@ async function doProcessDocMetadata({
     slug: docSlug,
     permalink,
     draft,
+    unlisted,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
     tags: normalizeFrontMatterTags(versionMetadata.tagsPath, frontMatter.tags),
     version: versionMetadata.versionName,
@@ -333,25 +310,27 @@ export async function processDocMetadata(args: {
   }
 }
 
-export function addDocNavigation(
-  docsBase: DocMetadataBase[],
-  sidebarsUtils: SidebarsUtils,
-  sidebarFilePath: string,
-): LoadedVersion['docs'] {
-  const docsById = createDocsByIdIndex(docsBase);
+function getUnlistedIds(docs: DocMetadataBase[]): Set<string> {
+  return new Set(docs.filter((doc) => doc.unlisted).map((doc) => doc.id));
+}
 
-  sidebarsUtils.checkSidebarsDocIds(
-    docsBase.flatMap(getDocIds),
-    sidebarFilePath,
-  );
+export function addDocNavigation({
+  docs,
+  sidebarsUtils,
+}: {
+  docs: DocMetadataBase[];
+  sidebarsUtils: SidebarsUtils;
+}): LoadedVersion['docs'] {
+  const docsById = createDocsByIdIndex(docs);
+  const unlistedIds = getUnlistedIds(docs);
 
   // Add sidebar/next/previous to the docs
   function addNavData(doc: DocMetadataBase): DocMetadata {
-    const navigation = sidebarsUtils.getDocNavigation(
-      doc.unversionedId,
-      doc.id,
-      doc.frontMatter.displayed_sidebar,
-    );
+    const navigation = sidebarsUtils.getDocNavigation({
+      docId: doc.id,
+      displayedSidebar: doc.frontMatter.displayed_sidebar,
+      unlistedIds,
+    });
 
     const toNavigationLinkByDocId = (
       docId: string | null | undefined,
@@ -367,6 +346,10 @@ export function addDocNavigation(
           `Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`,
         );
       }
+      // Gracefully handle explicitly providing an unlisted doc ID in production
+      if (navDoc.unlisted) {
+        return undefined;
+      }
       return toDocNavigationLink(navDoc);
     };
 
@@ -382,7 +365,7 @@ export function addDocNavigation(
     return {...doc, sidebar: navigation.sidebarName, previous, next};
   }
 
-  const docsWithNavigation = docsBase.map(addNavData);
+  const docsWithNavigation = docs.map(addNavData);
   // Sort to ensure consistent output for tests
   docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
   return docsWithNavigation;
@@ -409,16 +392,12 @@ export function getMainDocId({
     if (versionHomeDoc) {
       return versionHomeDoc;
     } else if (firstDocIdOfFirstSidebar) {
-      return docs.find(
-        (doc) =>
-          doc.id === firstDocIdOfFirstSidebar ||
-          doc.unversionedId === firstDocIdOfFirstSidebar,
-      )!;
+      return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar)!;
     }
     return docs[0]!;
   }
 
-  return getMainDoc().unversionedId;
+  return getMainDoc().id;
 }
 
 // By convention, Docusaurus considers some docs are "indexes":
@@ -462,25 +441,9 @@ export function toCategoryIndexMatcherParam({
   };
 }
 
-// Return both doc ids
-// TODO legacy retro-compatibility due to old versioned sidebars using
-// versioned doc ids ("id" should be removed & "versionedId" should be renamed
-// to "id")
-export function getDocIds(doc: DocMetadataBase): [string, string] {
-  return [doc.unversionedId, doc.id];
-}
-
-// Docs are indexed by both versioned and unversioned ids at the same time
-// TODO legacy retro-compatibility due to old versioned sidebars using
-// versioned doc ids ("id" should be removed & "versionedId" should be renamed
-// to "id")
-export function createDocsByIdIndex<
-  Doc extends {id: string; unversionedId: string},
->(docs: Doc[]): {[docId: string]: Doc} {
-  return Object.fromEntries(
-    docs.flatMap((doc) => [
-      [doc.unversionedId, doc],
-      [doc.id, doc],
-    ]),
-  );
+// Docs are indexed by their id
+export function createDocsByIdIndex<Doc extends {id: string}>(
+  docs: Doc[],
+): {[docId: string]: Doc} {
+  return _.keyBy(docs, (d) => d.id);
 }

package/src/frontMatter.ts

@@ -11,6 +11,7 @@ import {
   FrontMatterTagsSchema,
   FrontMatterTOCHeadingLevels,
   validateFrontMatter,
+  ContentVisibilitySchema,
 } from '@docusaurus/utils-validation';
 import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
 
@@ -43,7 +44,6 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   parse_number_prefixes: Joi.boolean(),
   pagination_next: Joi.string().allow(null),
   pagination_prev: Joi.string().allow(null),
-  draft: Joi.boolean(),
   ...FrontMatterTOCHeadingLevels,
   last_update: Joi.object({
     author: Joi.string(),
@@ -54,7 +54,9 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
       'object.missing': FrontMatterLastUpdateErrorMessage,
       'object.base': FrontMatterLastUpdateErrorMessage,
     }),
-}).unknown();
+})
+  .unknown()
+  .concat(ContentVisibilitySchema);
 
 export function validateDocFrontMatter(frontMatter: {
   [key: string]: unknown;

package/src/globalData.ts

@@ -21,8 +21,13 @@ import type {Sidebars} from './sidebars/types';
 
 function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {
-    id: doc.unversionedId,
+    id: doc.id,
     path: doc.permalink,
+
+    // optimize global data size: do not add unlisted: false/undefined
+    ...(doc.unlisted && {unlisted: doc.unlisted}),
+
+    // TODO optimize size? remove attribute when no sidebar (breaking change?)
     sidebar: doc.sidebar,
   };
 }
@@ -51,10 +56,7 @@ function toGlobalSidebars(
         path:
           firstLink.type === 'generated-index'
             ? firstLink.permalink
-            : version.docs.find(
-                (doc) =>
-                  doc.id === firstLink.id || doc.unversionedId === firstLink.id,
-              )!.permalink,
+            : version.docs.find((doc) => doc.id === firstLink.id)!.permalink,
         label: firstLink.label,
       },
     };
@@ -71,7 +73,7 @@ export function toGlobalDataVersion(version: FullVersion): GlobalVersion {
     docs: version.docs
       .map(toGlobalDataDoc)
       .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
-    draftIds: version.drafts.map((doc) => doc.unversionedId),
+    draftIds: version.drafts.map((doc) => doc.id),
     sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }