@docusaurus/plugin-content-docs 2.4.1 → 3.0.0-beta.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/generator.ts

@@ -138,7 +138,11 @@ Available doc IDs:
     ): WithPosition<SidebarItemDoc> {
       const {
         sidebarPosition: position,
-        frontMatter: {sidebar_label: label, sidebar_class_name: className},
+        frontMatter: {
+          sidebar_label: label,
+          sidebar_class_name: className,
+          sidebar_custom_props: customProps,
+        },
       } = getDoc(id);
       return {
         type: 'doc',
@@ -149,6 +153,7 @@ Available doc IDs:
         // sidebar
         ...(label !== undefined && {label}),
         ...(className !== undefined && {className}),
+        ...(customProps !== undefined && {customProps}),
       };
     }
     function createCategoryItem(

package/src/sidebars/postProcessor.ts

@@ -7,7 +7,6 @@
 
 import _ from 'lodash';
 import {normalizeUrl} from '@docusaurus/utils';
-import {getDocIds} from '../docs';
 import type {
   SidebarItem,
   Sidebars,
@@ -102,7 +101,7 @@ export function postProcessSidebars(
   sidebars: ProcessedSidebars,
   params: SidebarProcessorParams,
 ): Sidebars {
-  const draftIds = new Set(params.drafts.flatMap(getDocIds));
+  const draftIds = new Set(params.drafts.map((d) => d.id));
 
   return _.mapValues(sidebars, (sidebar) =>
     sidebar

package/src/sidebars/processor.ts

@@ -33,7 +33,6 @@ function toSidebarItemsGeneratorDoc(
 ): SidebarItemsGeneratorDoc {
   return _.pick(doc, [
     'id',
-    'unversionedId',
     'title',
     'frontMatter',
     'source',

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;
@@ -228,7 +235,6 @@ export type CategoryMetadataFile = {
 export type SidebarItemsGeneratorDoc = Pick<
   DocMetadataBase,
   | 'id'
-  | 'unversionedId'
   | 'title'
   | 'frontMatter'
   | 'source'

package/src/sidebars/utils.ts

@@ -23,6 +23,7 @@ import type {
 import type {
   DocMetadataBase,
   PropNavigationLink,
+  VersionMetadata,
 } from '@docusaurus/plugin-content-docs';
 
 export function isCategoriesShorthand(
@@ -135,11 +136,11 @@ 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: {
+    docId: string;
+    displayedSidebar: string | null | undefined;
+    unlistedIds: Set<string>;
+  }) => SidebarNavigation;
   getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
   getCategoryGeneratedIndexNavigation: (
     categoryGeneratedIndexPermalink: string,
@@ -162,7 +163,22 @@ export type SidebarsUtils = {
       }
     | undefined;
 
-  checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
+  checkLegacyVersionedSidebarNames: ({
+    versionMetadata,
+  }: {
+    sidebarFilePath: string;
+    versionMetadata: VersionMetadata;
+  }) => void;
+
+  checkSidebarsDocIds: ({
+    allDocIds,
+    sidebarFilePath,
+    versionMetadata,
+  }: {
+    allDocIds: string[];
+    sidebarFilePath: string;
+    versionMetadata: VersionMetadata;
+  }) => void;
 };
 
 export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
@@ -192,31 +208,45 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     };
   }
 
-  function getDocNavigation(
-    unversionedId: string,
-    versionedId: string,
-    displayedSidebar: string | null | undefined,
-  ): SidebarNavigation {
-    // TODO legacy id retro-compatibility!
-    let docId = unversionedId;
-    let sidebarName =
+  function getDocNavigation({
+    docId,
+    displayedSidebar,
+    unlistedIds,
+  }: {
+    docId: string;
+    displayedSidebar: string | null | undefined;
+    unlistedIds: Set<string>;
+  }): SidebarNavigation {
+    const sidebarName =
       displayedSidebar === undefined
         ? getSidebarNameByDocId(docId)
         : displayedSidebar;
-    if (sidebarName === undefined) {
-      docId = versionedId;
-      sidebarName = getSidebarNameByDocId(docId);
-    }
 
     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;
@@ -280,19 +310,115 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     };
   }
 
-  function checkSidebarsDocIds(validDocIds: string[], sidebarFilePath: string) {
+  // TODO remove in Docusaurus v4
+  function getLegacyVersionedPrefix(versionMetadata: VersionMetadata): string {
+    return `version-${versionMetadata.versionName}/`;
+  }
+
+  // In early v2, sidebar names used to be versioned
+  // example: "version-2.0.0-alpha.66/my-sidebar-name"
+  // In v3 it's not the case anymore and we throw an error to explain
+  // TODO remove in Docusaurus v4
+  function checkLegacyVersionedSidebarNames({
+    versionMetadata,
+    sidebarFilePath,
+  }: {
+    versionMetadata: VersionMetadata;
+    sidebarFilePath: string;
+  }): void {
+    const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
+    const legacySidebarNames = Object.keys(sidebars).filter((sidebarName) =>
+      sidebarName.startsWith(illegalPrefix),
+    );
+    if (legacySidebarNames.length > 0) {
+      throw new Error(
+        `Invalid sidebar file at "${toMessageRelativeFilePath(
+          sidebarFilePath,
+        )}".
+These legacy versioned sidebar names are not supported anymore in Docusaurus v3:
+- ${legacySidebarNames.sort().join('\n- ')}
+
+The sidebar names you should now use are:
+- ${legacySidebarNames
+          .sort()
+          .map((legacyName) => legacyName.split('/').splice(1).join('/'))
+          .join('\n- ')}
+
+Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
+This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
+`,
+      );
+    }
+  }
+
+  // throw a better error message for Docusaurus v3 breaking change
+  // TODO this can be removed in Docusaurus v4
+  function handleLegacyVersionedDocIds({
+    invalidDocIds,
+    sidebarFilePath,
+    versionMetadata,
+  }: {
+    invalidDocIds: string[];
+    sidebarFilePath: string;
+    versionMetadata: VersionMetadata;
+  }) {
+    const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
+
+    // In older v2.0 alpha/betas, versioned docs had a legacy versioned prefix
+    // Example: "version-1.4/my-doc-id"
+    //
+    const legacyVersionedDocIds = invalidDocIds.filter((docId) =>
+      docId.startsWith(illegalPrefix),
+    );
+    if (legacyVersionedDocIds.length > 0) {
+      throw new Error(
+        `Invalid sidebar file at "${toMessageRelativeFilePath(
+          sidebarFilePath,
+        )}".
+These legacy versioned document ids are not supported anymore in Docusaurus v3:
+- ${legacyVersionedDocIds.sort().join('\n- ')}
+
+The document ids you should now use are:
+- ${legacyVersionedDocIds
+          .sort()
+          .map((legacyId) => legacyId.split('/').splice(1).join('/'))
+          .join('\n- ')}
+
+Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
+This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
+`,
+      );
+    }
+  }
+
+  function checkSidebarsDocIds({
+    allDocIds,
+    sidebarFilePath,
+    versionMetadata,
+  }: {
+    allDocIds: string[];
+    sidebarFilePath: string;
+    versionMetadata: VersionMetadata;
+  }) {
     const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
-    const invalidSidebarDocIds = _.difference(allSidebarDocIds, validDocIds);
-    if (invalidSidebarDocIds.length > 0) {
+    const invalidDocIds = _.difference(allSidebarDocIds, allDocIds);
+
+    if (invalidDocIds.length > 0) {
+      handleLegacyVersionedDocIds({
+        invalidDocIds,
+        sidebarFilePath,
+        versionMetadata,
+      });
       throw new Error(
         `Invalid sidebar file at "${toMessageRelativeFilePath(
           sidebarFilePath,
         )}".
 These sidebar document ids do not exist:
-- ${invalidSidebarDocIds.sort().join('\n- ')}
+- ${invalidDocIds.sort().join('\n- ')}
 
 Available document ids are:
-- ${_.uniq(validDocIds).sort().join('\n- ')}`,
+- ${_.uniq(allDocIds).sort().join('\n- ')}
+`,
       );
     }
   }
@@ -346,6 +472,7 @@ Available document ids are:
     getDocNavigation,
     getCategoryGeneratedIndexList,
     getCategoryGeneratedIndexNavigation,
+    checkLegacyVersionedSidebarNames,
     checkSidebarsDocIds,
     getFirstLink: (id) => getFirstLink(sidebars[id]!),
   };

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/translations.ts

@@ -40,23 +40,6 @@ function getVersionFileName(versionName: string): string {
   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,
-}: {
-  versionName: string;
-  sidebarName: string;
-}): string {
-  if (versionName === CURRENT_VERSION_NAME || !sidebarName.includes('/')) {
-    return sidebarName;
-  }
-  const [, ...rest] = sidebarName.split('/');
-  return rest.join('/');
-}
-
 function getSidebarTranslationFileContent(
   sidebar: Sidebar,
   sidebarName: string,
@@ -199,13 +182,9 @@ function getSidebarsTranslations(
   version: LoadedVersion,
 ): TranslationFileContent {
   return mergeTranslations(
-    Object.entries(version.sidebars).map(([sidebarName, sidebar]) => {
-      const normalizedSidebarName = getNormalizedSidebarName({
-        sidebarName,
-        versionName: version.versionName,
-      });
-      return getSidebarTranslationFileContent(sidebar, normalizedSidebarName);
-    }),
+    Object.entries(version.sidebars).map(([sidebarName, sidebar]) =>
+      getSidebarTranslationFileContent(sidebar, sidebarName),
+    ),
   );
 }
 function translateSidebars(
@@ -215,10 +194,7 @@ function translateSidebars(
   return _.mapValues(version.sidebars, (sidebar, sidebarName) =>
     translateSidebar({
       sidebar,
-      sidebarName: getNormalizedSidebarName({
-        sidebarName,
-        versionName: version.versionName,
-      }),
+      sidebarName,
       sidebarsTranslations,
     }),
   );