@docusaurus/plugin-content-docs 2.4.0 → 3.0.0-alpha.0

package/src/docs.ts

@@ -18,6 +18,8 @@ import {
   posixPath,
   Globby,
   normalizeFrontMatterTags,
+  isUnlisted,
+  isDraft,
 } from '@docusaurus/utils';
 
 import {getFileLastUpdate} from './lastUpdate';
@@ -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,
@@ -268,7 +258,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 {
@@ -299,6 +290,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 +325,32 @@ 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,
+  sidebarFilePath,
+}: {
+  docs: DocMetadataBase[];
+  sidebarsUtils: SidebarsUtils;
+  sidebarFilePath: string;
+}): LoadedVersion['docs'] {
+  const docsById = createDocsByIdIndex(docs);
+  const unlistedIds = getUnlistedIds(docs);
+
+  sidebarsUtils.checkSidebarsDocIds(docs.flatMap(getDocIds), sidebarFilePath);
 
   // 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({
+      unversionedId: doc.unversionedId,
+      versionedId: doc.id,
+      displayedSidebar: doc.frontMatter.displayed_sidebar,
+      unlistedIds,
+    });
 
     const toNavigationLinkByDocId = (
       docId: string | null | undefined,
@@ -367,6 +366,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 +385,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;

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

@@ -23,6 +23,11 @@ function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {
     id: doc.unversionedId,
     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,
   };
 }

package/src/index.ts

@@ -27,22 +27,18 @@ import {
   addDocNavigation,
   type DocEnv,
 } from './docs';
-import {readVersionsMetadata} from './versions';
+import {readVersionsMetadata, toFullVersion} from './versions';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
 import {toGlobalDataVersion} from './globalData';
-import {toTagDocListProp} from './props';
-import {getCategoryGeneratedIndexMetadataList} from './categoryGeneratedIndex';
 import {
   translateLoadedContent,
   getLoadedContentTranslationFiles,
 } from './translations';
-import {getVersionTags} from './tags';
-import {createVersionRoutes} from './routes';
+import {createAllRoutes} from './routes';
 import {createSidebarsUtils} from './sidebars/utils';
 
 import type {
-  PropTagsListPage,
   PluginOptions,
   DocMetadataBase,
   VersionMetadata,
@@ -55,7 +51,6 @@ import type {
   SourceToPermalink,
   DocFile,
   DocsMarkdownOption,
-  VersionTag,
   FullVersion,
 } from './types';
 import type {RuleSetRule} from 'webpack';
@@ -80,6 +75,9 @@ export default async function pluginContentDocs(
   const aliasedSource = (source: string) =>
     `~docs/${posixPath(path.relative(pluginDataDirRoot, source))}`;
 
+  // TODO env should be injected into all plugins
+  const env = process.env.NODE_ENV as DocEnv;
+
   return {
     name: 'docusaurus-plugin-content-docs',
 
@@ -148,7 +146,7 @@ export default async function pluginContentDocs(
             versionMetadata,
             context,
             options,
-            env: process.env.NODE_ENV as DocEnv,
+            env,
           });
         }
         return Promise.all(docFiles.map(processVersionDoc));
@@ -161,6 +159,9 @@ export default async function pluginContentDocs(
           versionMetadata,
         );
 
+        // 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] = _.partition(docsBase, (doc) => doc.draft);
 
         const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
@@ -180,11 +181,11 @@ export default async function pluginContentDocs(
 
         return {
           ...versionMetadata,
-          docs: addDocNavigation(
+          docs: addDocNavigation({
             docs,
             sidebarsUtils,
-            versionMetadata.sidebarFilePath as string,
-          ),
+            sidebarFilePath: versionMetadata.sidebarFilePath as string,
+          }),
           drafts,
           sidebars,
         };
@@ -209,107 +210,24 @@ export default async function pluginContentDocs(
     },
 
     async contentLoaded({content, actions}) {
-      const {loadedVersions} = content;
-      const {
-        docLayoutComponent,
-        docItemComponent,
-        docCategoryGeneratedIndexComponent,
-        breadcrumbs,
-      } = options;
-      const {addRoute, createData, setGlobalData} = actions;
-      const versions: FullVersion[] = loadedVersions.map((version) => {
-        const sidebarsUtils = createSidebarsUtils(version.sidebars);
-        return {
-          ...version,
-          sidebarsUtils,
-          categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
-            docs: version.docs,
-            sidebarsUtils,
-          }),
-        };
+      const versions: FullVersion[] = content.loadedVersions.map(toFullVersion);
+
+      await createAllRoutes({
+        baseUrl,
+        versions,
+        options,
+        actions,
+        aliasedSource,
       });
 
-      async function createVersionTagsRoutes(version: FullVersion) {
-        const versionTags = getVersionTags(version.docs);
-
-        // TODO tags should be a sub route of the version route
-        async function createTagsListPage() {
-          const tagsProp: PropTagsListPage['tags'] = Object.values(
-            versionTags,
-          ).map((tagValue) => ({
-            label: tagValue.label,
-            permalink: tagValue.permalink,
-            count: tagValue.docIds.length,
-          }));
-
-          // Only create /tags page if there are tags.
-          if (tagsProp.length > 0) {
-            const tagsPropPath = await createData(
-              `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
-              JSON.stringify(tagsProp, null, 2),
-            );
-            addRoute({
-              path: version.tagsPath,
-              exact: true,
-              component: options.docTagsListComponent,
-              modules: {
-                tags: aliasedSource(tagsPropPath),
-              },
-            });
-          }
-        }
-
-        // TODO tags should be a sub route of the version route
-        async function createTagDocListPage(tag: VersionTag) {
-          const tagProps = toTagDocListProp({
-            allTagsPath: version.tagsPath,
-            tag,
-            docs: version.docs,
-          });
-          const tagPropPath = await createData(
-            `${docuHash(`tag-${tag.permalink}`)}.json`,
-            JSON.stringify(tagProps, null, 2),
-          );
-          addRoute({
-            path: tag.permalink,
-            component: options.docTagDocListComponent,
-            exact: true,
-            modules: {
-              tag: aliasedSource(tagPropPath),
-            },
-          });
-        }
-
-        await createTagsListPage();
-        await Promise.all(Object.values(versionTags).map(createTagDocListPage));
-      }
-
-      await Promise.all(
-        versions.map((version) =>
-          createVersionRoutes({
-            version,
-            docItemComponent,
-            docLayoutComponent,
-            docCategoryGeneratedIndexComponent,
-            pluginId,
-            aliasedSource,
-            actions,
-          }),
-        ),
-      );
-
-      // TODO tags should be a sub route of the version route
-      await Promise.all(versions.map(createVersionTagsRoutes));
-
-      setGlobalData({
+      actions.setGlobalData({
         path: normalizeUrl([baseUrl, options.routeBasePath]),
         versions: versions.map(toGlobalDataVersion),
-        breadcrumbs,
+        breadcrumbs: options.breadcrumbs,
       });
     },
 
     configureWebpack(_config, isServer, utils, content) {
-      const {getJSLoader} = utils;
       const {
         rehypePlugins,
         remarkPlugins,
@@ -344,7 +262,6 @@ export default async function pluginContentDocs(
           test: /\.mdx?$/i,
           include: contentDirs,
           use: [
-            getJSLoader({isServer}),
             {
               loader: require.resolve('@docusaurus/mdx-loader'),
               options: {

package/src/options.ts

@@ -11,6 +11,7 @@ import {
   RemarkPluginsSchema,
   RehypePluginsSchema,
   AdmonitionsSchema,
+  RouteBasePathSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
 import {GlobExcludeDefault} from '@docusaurus/utils';
@@ -30,7 +31,9 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   exclude: GlobExcludeDefault,
   sidebarItemsGenerator: DefaultSidebarItemsGenerator,
   numberPrefixParser: DefaultNumberPrefixParser,
-  docLayoutComponent: '@theme/DocPage',
+  docsRootComponent: '@theme/DocsRoot',
+  docVersionRootComponent: '@theme/DocVersionRoot',
+  docRootComponent: '@theme/DocRoot',
   docItemComponent: '@theme/DocItem',
   docTagDocListComponent: '@theme/DocTagDocListPage',
   docTagsListComponent: '@theme/DocTagsListPage',
@@ -71,10 +74,7 @@ const OptionsSchema = Joi.object<PluginOptions>({
   editUrl: Joi.alternatives().try(URISchema, Joi.function()),
   editCurrentVersion: Joi.boolean().default(DEFAULT_OPTIONS.editCurrentVersion),
   editLocalizedFiles: Joi.boolean().default(DEFAULT_OPTIONS.editLocalizedFiles),
-  routeBasePath: Joi.string()
-    // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
-    // .allow('') ""
-    .default(DEFAULT_OPTIONS.routeBasePath),
+  routeBasePath: RouteBasePathSchema.default(DEFAULT_OPTIONS.routeBasePath),
   tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
   // @ts-expect-error: deprecated
   homePageId: Joi.any().forbidden().messages({
@@ -104,7 +104,11 @@ const OptionsSchema = Joi.object<PluginOptions>({
       }),
     )
     .default(() => DEFAULT_OPTIONS.numberPrefixParser),
-  docLayoutComponent: Joi.string().default(DEFAULT_OPTIONS.docLayoutComponent),
+  docsRootComponent: Joi.string().default(DEFAULT_OPTIONS.docsRootComponent),
+  docVersionRootComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docVersionRootComponent,
+  ),
+  docRootComponent: Joi.string().default(DEFAULT_OPTIONS.docRootComponent),
   docItemComponent: Joi.string().default(DEFAULT_OPTIONS.docItemComponent),
   docTagsListComponent: Joi.string().default(
     DEFAULT_OPTIONS.docTagsListComponent,

package/src/plugin-content-docs.d.ts

@@ -198,10 +198,24 @@ declare module '@docusaurus/plugin-content-docs' {
        */
       exclude: string[];
       /**
-       * Root layout component of each doc page. Provides the version data
-       * context, and is not unmounted when switching docs.
+       * Parent component of all the docs plugin pages (including all versions).
+       * Stays mounted when navigation between docs pages and versions.
        */
-      docLayoutComponent: string;
+      docsRootComponent: string;
+      /**
+       * Parent component of all docs pages of an individual version:
+       * - docs pages with sidebars
+       * - tags pages
+       * Stays mounted when navigation between pages of that specific version.
+       */
+      docVersionRootComponent: string;
+      /**
+       * Parent component of all docs pages with sidebars:
+       * - regular docs pages
+       * - category generated index pages
+       * Stays mounted when navigation between such pages.
+       */
+      docRootComponent: string;
       /** Main doc container, with TOC, pagination, etc. */
       docItemComponent: string;
       /** Root component of the "docs containing tag X" page. */
@@ -384,6 +398,8 @@ declare module '@docusaurus/plugin-content-docs' {
     pagination_prev?: string | null;
     /** Should this doc be excluded from production builds? */
     draft?: boolean;
+    /** Should this doc be accessible but hidden in production builds? */
+    unlisted?: boolean;
     /** Allows overriding the last updated author and/or date. */
     last_update?: FileChange;
   };
@@ -434,6 +450,11 @@ declare module '@docusaurus/plugin-content-docs' {
      * Draft docs will be excluded for production environment.
      */
     draft: boolean;
+    /**
+     * Unlisted docs are accessible when directly visible, but will be hidden
+     * from the sidebar and pagination in production.
+     */
+    unlisted: boolean;
     /**
      * Position in an autogenerated sidebar slice, acquired through front matter
      * or number prefix.
@@ -610,14 +631,32 @@ declare module '@theme/DocBreadcrumbs' {
   export default function DocBreadcrumbs(): JSX.Element;
 }
 
-declare module '@theme/DocPage' {
+declare module '@theme/DocsRoot' {
+  import type {RouteConfigComponentProps} from 'react-router-config';
+  import type {Required} from 'utility-types';
+
+  export interface Props extends Required<RouteConfigComponentProps, 'route'> {}
+
+  export default function DocsRoot(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocVersionRoot' {
   import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
   import type {RouteConfigComponentProps} from 'react-router-config';
   import type {Required} from 'utility-types';
 
   export interface Props extends Required<RouteConfigComponentProps, 'route'> {
-    readonly versionMetadata: PropVersionMetadata;
+    readonly version: PropVersionMetadata;
   }
 
-  export default function DocPage(props: Props): JSX.Element;
+  export default function DocVersionRoot(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocRoot' {
+  import type {RouteConfigComponentProps} from 'react-router-config';
+  import type {Required} from 'utility-types';
+
+  export interface Props extends Required<RouteConfigComponentProps, 'route'> {}
+
+  export default function DocRoot(props: Props): JSX.Element;
 }

package/src/props.ts

@@ -7,7 +7,7 @@
 
 import _ from 'lodash';
 import {createDocsByIdIndex} from './docs';
-import type {VersionTag} from './types';
+import type {VersionTag, VersionTags} from './types';
 import type {
   SidebarItemDoc,
   SidebarItem,
@@ -21,12 +21,44 @@ import type {
   PropSidebarItemCategory,
   PropTagDocList,
   PropTagDocListDoc,
+  PropTagsListPage,
   PropSidebarItemLink,
   PropVersionDocs,
   DocMetadata,
   LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
 
+export function toSidebarDocItemLinkProp({
+  item,
+  doc,
+}: {
+  item: SidebarItemDoc;
+  doc: Pick<
+    DocMetadata,
+    'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter' | 'unversionedId'
+  >;
+}): PropSidebarItemLink {
+  const {
+    title,
+    permalink,
+    frontMatter: {
+      sidebar_label: sidebarLabel,
+      sidebar_custom_props: customProps,
+    },
+    unlisted,
+    unversionedId,
+  } = doc;
+  return {
+    type: 'link',
+    label: sidebarLabel ?? item.label ?? title,
+    href: permalink,
+    className: item.className,
+    customProps: item.customProps ?? customProps,
+    docId: unversionedId,
+    unlisted,
+  };
+}
+
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
   const docsById = createDocsByIdIndex(loadedVersion.docs);
 
@@ -43,21 +75,8 @@ Available document ids are:
   }
 
   const convertDocLink = (item: SidebarItemDoc): PropSidebarItemLink => {
-    const docMetadata = getDocById(item.id);
-    const {
-      title,
-      permalink,
-      frontMatter: {sidebar_label: sidebarLabel},
-    } = docMetadata;
-    return {
-      type: 'link',
-      label: sidebarLabel ?? item.label ?? title,
-      href: permalink,
-      className: item.className,
-      customProps:
-        item.customProps ?? docMetadata.frontMatter.sidebar_custom_props,
-      docId: docMetadata.unversionedId,
-    };
+    const doc = getDocById(item.id);
+    return toSidebarDocItemLinkProp({item, doc});
   };
 
   function getCategoryLinkHref(
@@ -73,6 +92,15 @@ Available document ids are:
     }
   }
 
+  function getCategoryLinkUnlisted(
+    link: SidebarItemCategoryLink | undefined,
+  ): boolean {
+    if (link?.type === 'doc') {
+      return getDocById(link.id).unlisted;
+    }
+    return false;
+  }
+
   function getCategoryLinkCustomProps(
     link: SidebarItemCategoryLink | undefined,
   ) {
@@ -87,12 +115,14 @@ Available document ids are:
   function convertCategory(item: SidebarItemCategory): PropSidebarItemCategory {
     const {link, ...rest} = item;
     const href = getCategoryLinkHref(link);
+    const linkUnlisted = getCategoryLinkUnlisted(link);
     const customProps = item.customProps ?? getCategoryLinkCustomProps(link);
 
     return {
       ...rest,
       items: item.items.map(normalizeItem),
       ...(href && {href}),
+      ...(linkUnlisted && {linkUnlisted}),
       ...(customProps && {customProps}),
     };
   }
@@ -179,5 +209,18 @@ export function toTagDocListProp({
     allTagsPath,
     count: tag.docIds.length,
     items: toDocListProp(),
+    unlisted: tag.unlisted,
   };
 }
+
+export function toTagsListTagsProp(
+  versionTags: VersionTags,
+): PropTagsListPage['tags'] {
+  return Object.values(versionTags)
+    .filter((tagValue) => !tagValue.unlisted)
+    .map((tagValue) => ({
+      label: tagValue.label,
+      permalink: tagValue.permalink,
+      count: tagValue.docIds.length,
+    }));
+}