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

package/src/routes.ts

@@ -5,30 +5,32 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
 import logger from '@docusaurus/logger';
-import {docuHash, createSlugger} from '@docusaurus/utils';
-import {toVersionMetadataProp} from './props';
+import {docuHash, createSlugger, normalizeUrl} from '@docusaurus/utils';
+import {
+  toTagDocListProp,
+  toTagsListTagsProp,
+  toVersionMetadataProp,
+} from './props';
+import {getVersionTags} from './tags';
 import type {PluginContentLoadedActions, RouteConfig} from '@docusaurus/types';
-import type {FullVersion} from './types';
+import type {FullVersion, VersionTag} from './types';
 import type {
   CategoryGeneratedIndexMetadata,
-  DocMetadata,
+  PluginOptions,
+  PropTagsListPage,
 } from '@docusaurus/plugin-content-docs';
 
-export async function createCategoryGeneratedIndexRoutes({
+async function buildVersionCategoryGeneratedIndexRoutes({
   version,
   actions,
-  docCategoryGeneratedIndexComponent,
+  options,
   aliasedSource,
-}: {
-  version: FullVersion;
-  actions: PluginContentLoadedActions;
-  docCategoryGeneratedIndexComponent: string;
-  aliasedSource: (str: string) => string;
-}): Promise<RouteConfig[]> {
+}: BuildVersionRoutesParam): Promise<RouteConfig[]> {
   const slugs = createSlugger();
 
-  async function createCategoryGeneratedIndexRoute(
+  async function buildCategoryGeneratedIndexRoute(
     categoryGeneratedIndex: CategoryGeneratedIndexMetadata,
   ): Promise<RouteConfig> {
     const {sidebar, ...prop} = categoryGeneratedIndex;
@@ -44,7 +46,7 @@ export async function createCategoryGeneratedIndexRoutes({
 
     return {
       path: categoryGeneratedIndex.permalink,
-      component: docCategoryGeneratedIndexComponent,
+      component: options.docCategoryGeneratedIndexComponent,
       exact: true,
       modules: {
         categoryGeneratedIndex: aliasedSource(propData),
@@ -56,21 +58,17 @@ export async function createCategoryGeneratedIndexRoutes({
   }
 
   return Promise.all(
-    version.categoryGeneratedIndices.map(createCategoryGeneratedIndexRoute),
+    version.categoryGeneratedIndices.map(buildCategoryGeneratedIndexRoute),
   );
 }
 
-export async function createDocRoutes({
-  docs,
+async function buildVersionDocRoutes({
+  version,
   actions,
-  docItemComponent,
-}: {
-  docs: DocMetadata[];
-  actions: PluginContentLoadedActions;
-  docItemComponent: string;
-}): Promise<RouteConfig[]> {
+  options,
+}: BuildVersionRoutesParam): Promise<RouteConfig[]> {
   return Promise.all(
-    docs.map(async (metadataItem) => {
+    version.docs.map(async (metadataItem) => {
       await actions.createData(
         // Note that this created data path must be in sync with
         // metadataPath provided to mdx-loader.
@@ -80,12 +78,12 @@ export async function createDocRoutes({
 
       const docRoute: RouteConfig = {
         path: metadataItem.permalink,
-        component: docItemComponent,
+        component: options.docItemComponent,
         exact: true,
         modules: {
           content: metadataItem.source,
         },
-        // Because the parent (DocPage) comp need to access it easily
+        // Because the parent (DocRoot) comp need to access it easily
         // This permits to render the sidebar once without unmount/remount when
         // navigating (and preserve sidebar state)
         ...(metadataItem.sidebar && {
@@ -98,62 +96,160 @@ export async function createDocRoutes({
   );
 }
 
-export async function createVersionRoutes({
-  version,
-  actions,
-  docItemComponent,
-  docLayoutComponent,
-  docCategoryGeneratedIndexComponent,
-  pluginId,
-  aliasedSource,
-}: {
-  version: FullVersion;
-  actions: PluginContentLoadedActions;
-  docLayoutComponent: string;
-  docItemComponent: string;
-  docCategoryGeneratedIndexComponent: string;
-  pluginId: string;
-  aliasedSource: (str: string) => string;
-}): Promise<void> {
-  async function doCreateVersionRoutes(): Promise<void> {
-    const versionMetadata = toVersionMetadataProp(pluginId, version);
-    const versionMetadataPropPath = await actions.createData(
-      `${docuHash(`version-${version.versionName}-metadata-prop`)}.json`,
-      JSON.stringify(versionMetadata, null, 2),
-    );
+async function buildVersionSidebarRoute(param: BuildVersionRoutesParam) {
+  const [docRoutes, categoryGeneratedIndexRoutes] = await Promise.all([
+    buildVersionDocRoutes(param),
+    buildVersionCategoryGeneratedIndexRoutes(param),
+  ]);
+  const subRoutes = [...docRoutes, ...categoryGeneratedIndexRoutes];
+  return {
+    path: param.version.path,
+    exact: false,
+    component: param.options.docRootComponent,
+    routes: subRoutes,
+  };
+}
 
-    async function createVersionSubRoutes() {
-      const [docRoutes, sidebarsRoutes] = await Promise.all([
-        createDocRoutes({docs: version.docs, actions, docItemComponent}),
-        createCategoryGeneratedIndexRoutes({
-          version,
-          actions,
-          docCategoryGeneratedIndexComponent,
-          aliasedSource,
-        }),
-      ]);
+async function buildVersionTagsRoutes(
+  param: BuildVersionRoutesParam,
+): Promise<RouteConfig[]> {
+  const {version, options, actions, aliasedSource} = param;
+  const versionTags = getVersionTags(version.docs);
 
-      const routes = [...docRoutes, ...sidebarsRoutes];
-      return routes.sort((a, b) => a.path.localeCompare(b.path));
+  async function buildTagsListRoute(): Promise<RouteConfig | null> {
+    // Don't create a tags list page if there's no tag
+    if (Object.keys(versionTags).length === 0) {
+      return null;
     }
+    const tagsProp: PropTagsListPage['tags'] = toTagsListTagsProp(versionTags);
+    const tagsPropPath = await actions.createData(
+      `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
+      JSON.stringify(tagsProp, null, 2),
+    );
+    return {
+      path: version.tagsPath,
+      exact: true,
+      component: options.docTagsListComponent,
+      modules: {
+        tags: aliasedSource(tagsPropPath),
+      },
+    };
+  }
+
+  async function buildTagDocListRoute(tag: VersionTag): Promise<RouteConfig> {
+    const tagProps = toTagDocListProp({
+      allTagsPath: version.tagsPath,
+      tag,
+      docs: version.docs,
+    });
+    const tagPropPath = await actions.createData(
+      `${docuHash(`tag-${tag.permalink}`)}.json`,
+      JSON.stringify(tagProps, null, 2),
+    );
+    return {
+      path: tag.permalink,
+      component: options.docTagDocListComponent,
+      exact: true,
+      modules: {
+        tag: aliasedSource(tagPropPath),
+      },
+    };
+  }
+
+  const [tagsListRoute, allTagsDocListRoutes] = await Promise.all([
+    buildTagsListRoute(),
+    Promise.all(Object.values(versionTags).map(buildTagDocListRoute)),
+  ]);
+
+  return _.compact([tagsListRoute, ...allTagsDocListRoutes]);
+}
+
+type BuildVersionRoutesParam = Omit<BuildAllRoutesParam, 'versions'> & {
+  version: FullVersion;
+};
+
+async function buildVersionRoutes(
+  param: BuildVersionRoutesParam,
+): Promise<RouteConfig> {
+  const {version, actions, options, aliasedSource} = param;
 
-    actions.addRoute({
+  async function buildVersionSubRoutes() {
+    const [sidebarRoute, tagsRoutes] = await Promise.all([
+      buildVersionSidebarRoute(param),
+      buildVersionTagsRoutes(param),
+    ]);
+
+    return [sidebarRoute, ...tagsRoutes];
+  }
+
+  async function doBuildVersionRoutes(): Promise<RouteConfig> {
+    const versionProp = toVersionMetadataProp(options.id, version);
+    const versionPropPath = await actions.createData(
+      `${docuHash(`version-${version.versionName}-metadata-prop`)}.json`,
+      JSON.stringify(versionProp, null, 2),
+    );
+    const subRoutes = await buildVersionSubRoutes();
+    return {
       path: version.path,
-      // Allow matching /docs/* since this is the wrapping route
       exact: false,
-      component: docLayoutComponent,
-      routes: await createVersionSubRoutes(),
+      component: options.docVersionRootComponent,
+      routes: subRoutes,
       modules: {
-        versionMetadata: aliasedSource(versionMetadataPropPath),
+        version: aliasedSource(versionPropPath),
       },
       priority: version.routePriority,
-    });
+    };
   }
 
   try {
-    return await doCreateVersionRoutes();
+    return await doBuildVersionRoutes();
   } catch (err) {
     logger.error`Can't create version routes for version name=${version.versionName}`;
     throw err;
   }
 }
+
+type BuildAllRoutesParam = Omit<CreateAllRoutesParam, 'actions'> & {
+  actions: Omit<PluginContentLoadedActions, 'addRoute' | 'setGlobalData'>;
+};
+
+// TODO we want this buildAllRoutes function to be easily testable
+// Ideally, we should avoid side effects here (ie not injecting actions)
+export async function buildAllRoutes(
+  param: BuildAllRoutesParam,
+): Promise<RouteConfig[]> {
+  const subRoutes = await Promise.all(
+    param.versions.map((version) =>
+      buildVersionRoutes({
+        ...param,
+        version,
+      }),
+    ),
+  );
+
+  // all docs routes are wrapped under a single parent route, this ensures
+  // the theme layout never unmounts/remounts when navigating between versions
+  return [
+    {
+      path: normalizeUrl([param.baseUrl, param.options.routeBasePath]),
+      exact: false,
+      component: param.options.docsRootComponent,
+      routes: subRoutes,
+    },
+  ];
+}
+
+type CreateAllRoutesParam = {
+  baseUrl: string;
+  versions: FullVersion[];
+  options: PluginOptions;
+  actions: PluginContentLoadedActions;
+  aliasedSource: (str: string) => string;
+};
+
+export async function createAllRoutes(
+  param: CreateAllRoutesParam,
+): Promise<void> {
+  const routes = await buildAllRoutes(param);
+  routes.forEach(param.actions.addRoute);
+}

package/src/sidebars/types.ts

@@ -185,11 +185,18 @@ export type PropSidebarItemCategory = Expand<
   SidebarItemCategoryBase & {
     items: PropSidebarItem[];
     href?: string;
+
+    // Weird name => it would have been more convenient to have link.unlisted
+    // Note it is the category link that is unlisted, not the category itself
+    // We want to prevent users from clicking on an unlisted category link
+    // We can't use "href: undefined" otherwise sidebar item is not highlighted
+    linkUnlisted?: boolean;
   }
 >;
 
 export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
+  unlisted?: boolean;
 };
 
 export type PropSidebarItemHtml = SidebarItemHtml;

package/src/sidebars/utils.ts

@@ -135,11 +135,12 @@ export type SidebarsUtils = {
   sidebars: Sidebars;
   getFirstDocIdOfFirstSidebar: () => string | undefined;
   getSidebarNameByDocId: (docId: string) => string | undefined;
-  getDocNavigation: (
-    unversionedId: string,
-    versionedId: string,
-    displayedSidebar: string | null | undefined,
-  ) => SidebarNavigation;
+  getDocNavigation: (params: {
+    unversionedId: string;
+    versionedId: string;
+    displayedSidebar: string | null | undefined;
+    unlistedIds: Set<string>;
+  }) => SidebarNavigation;
   getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
   getCategoryGeneratedIndexNavigation: (
     categoryGeneratedIndexPermalink: string,
@@ -192,11 +193,17 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     };
   }
 
-  function getDocNavigation(
-    unversionedId: string,
-    versionedId: string,
-    displayedSidebar: string | null | undefined,
-  ): SidebarNavigation {
+  function getDocNavigation({
+    unversionedId,
+    versionedId,
+    displayedSidebar,
+    unlistedIds,
+  }: {
+    unversionedId: string;
+    versionedId: string;
+    displayedSidebar: string | null | undefined;
+    unlistedIds: Set<string>;
+  }): SidebarNavigation {
     // TODO legacy id retro-compatibility!
     let docId = unversionedId;
     let sidebarName =
@@ -211,12 +218,28 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     if (!sidebarName) {
       return emptySidebarNavigation();
     }
-    const navigationItems = sidebarNameToNavigationItems[sidebarName];
+    let navigationItems = sidebarNameToNavigationItems[sidebarName];
     if (!navigationItems) {
       throw new Error(
         `Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`,
       );
     }
+
+    // Filter unlisted items from navigation
+    navigationItems = navigationItems.filter((item) => {
+      if (item.type === 'doc' && unlistedIds.has(item.id)) {
+        return false;
+      }
+      if (
+        item.type === 'category' &&
+        item.link.type === 'doc' &&
+        unlistedIds.has(item.link.id)
+      ) {
+        return false;
+      }
+      return true;
+    });
+
     const currentItemIndex = navigationItems.findIndex((item) => {
       if (item.type === 'doc') {
         return item.id === docId;

package/src/tags.ts

@@ -6,15 +6,22 @@
  */
 
 import _ from 'lodash';
-import {groupTaggedItems} from '@docusaurus/utils';
+import {getTagVisibility, groupTaggedItems} from '@docusaurus/utils';
 import type {VersionTags} from './types';
 import type {DocMetadata} from '@docusaurus/plugin-content-docs';
 
 export function getVersionTags(docs: DocMetadata[]): VersionTags {
   const groups = groupTaggedItems(docs, (doc) => doc.tags);
-  return _.mapValues(groups, (group) => ({
-    label: group.tag.label,
-    docIds: group.items.map((item) => item.id),
-    permalink: group.tag.permalink,
-  }));
+  return _.mapValues(groups, ({tag, items: tagDocs}) => {
+    const tagVisibility = getTagVisibility({
+      items: tagDocs,
+      isUnlisted: (item) => item.unlisted,
+    });
+    return {
+      label: tag.label,
+      docIds: tagVisibility.listedItems.map((item) => item.id),
+      permalink: tag.permalink,
+      unlisted: tagVisibility.unlisted,
+    };
+  });
 }

package/src/types.ts

@@ -27,6 +27,7 @@ export type SourceToPermalink = {
 export type VersionTag = Tag & {
   /** All doc ids having this tag. */
   docIds: string[];
+  unlisted: boolean;
 };
 export type VersionTags = {
   [permalink: string]: VersionTag;

package/src/versions/index.ts

@@ -14,12 +14,16 @@ import {
   getVersionMetadataPaths,
   readVersionNames,
 } from './files';
+import {createSidebarsUtils} from '../sidebars/utils';
+import {getCategoryGeneratedIndexMetadataList} from '../categoryGeneratedIndex';
+import type {FullVersion} from '../types';
+import type {LoadContext} from '@docusaurus/types';
 import type {
+  LoadedVersion,
   PluginOptions,
   VersionBanner,
   VersionMetadata,
 } from '@docusaurus/plugin-content-docs';
-import type {LoadContext} from '@docusaurus/types';
 
 export type VersionContext = {
   /** The version name to get banner of. */
@@ -252,3 +256,15 @@ export async function readVersionsMetadata({
   );
   return versionsMetadata;
 }
+
+export function toFullVersion(version: LoadedVersion): FullVersion {
+  const sidebarsUtils = createSidebarsUtils(version.sidebars);
+  return {
+    ...version,
+    sidebarsUtils,
+    categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
+      docs: version.docs,
+      sidebarsUtils,
+    }),
+  };
+}