feat(content-docs): sidebar category linking to document or auto-generated index page

.eslintrc.js

@@ -52,6 +52,7 @@ module.exports = {
       {ignore: ['^@theme', '^@docusaurus', '^@generated', 'unist', 'mdast']},
     ],
     'import/extensions': OFF,
+    'no-inner-declarations': OFF,
     'header/header': [
       ERROR,
       'block',

packages/docusaurus-mdx-loader/package.json

@@ -28,7 +28,6 @@
     "escape-html": "^1.0.3",
     "file-loader": "^6.2.0",
     "fs-extra": "^10.0.0",
-    "github-slugger": "^1.4.0",
     "gray-matter": "^4.0.3",
     "mdast-util-to-string": "^2.0.0",
     "remark-emoji": "^2.1.0",

packages/docusaurus-mdx-loader/src/remark/headings/index.ts

@@ -7,19 +7,16 @@
 
 /* Based on remark-slug (https://github.com/remarkjs/remark-slug) and gatsby-remark-autolink-headers (https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-remark-autolink-headers) */
 
-import {parseMarkdownHeadingId} from '@docusaurus/utils';
+import {parseMarkdownHeadingId, createSlugger} from '@docusaurus/utils';
 import visit, {Visitor} from 'unist-util-visit';
 import toString from 'mdast-util-to-string';
-import Slugger from 'github-slugger';
 import type {Transformer} from 'unified';
 import type {Parent} from 'unist';
 import type {Heading, Text} from 'mdast';
 
-const slugs = new Slugger();
-
 function headings(): Transformer {
   const transformer: Transformer = (ast) => {
-    slugs.reset();
+    const slugs = createSlugger();
 
     const visitor: Visitor<Heading> = (headingNode) => {
       const data = headingNode.data || (headingNode.data = {});
@@ -29,7 +26,7 @@ function headings(): Transformer {
       let {id} = properties;
 
       if (id) {
-        id = slugs.slug(id, true);
+        id = slugs.slug(id, {maintainCase: true});
       } else {
         const headingTextNodes = headingNode.children.filter(
           ({type}) => !['html', 'jsx'].includes(type),

packages/docusaurus-plugin-content-docs/src/cli.ts

@@ -15,24 +15,23 @@ import path from 'path';
 import type {PathOptions, SidebarOptions} from './types';
 import {transformSidebarItems} from './sidebars/utils';
 import type {SidebarItem, NormalizedSidebars, Sidebar} from './sidebars/types';
-import {loadUnprocessedSidebars, resolveSidebarPathOption} from './sidebars';
+import {loadSidebarsFile, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 
 function createVersionedSidebarFile({
   siteDir,
   pluginId,
   sidebarPath,
   version,
-  options,
 }: {
   siteDir: string;
   pluginId: string;
   sidebarPath: string | false | undefined;
   version: string;
-  options: SidebarOptions;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  const loadedSidebars = loadUnprocessedSidebars(sidebarPath, options);
+  // Note: we don't need the sidebars file to be normalized: it's ok to let plugin option changes to impact versioned sidebars
+  const loadedSidebars = loadSidebarsFile(sidebarPath);
 
   // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
   const shouldCreateVersionedSidebarFile =
@@ -155,7 +154,6 @@ export function cliDocsVersionCommand(
     pluginId,
     version,
     sidebarPath: resolveSidebarPathOption(siteDir, sidebarPath),
-    options,
   });
 
   // Update versions.json file.

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -20,7 +20,7 @@ import {
   addTrailingPathSeparator,
   createAbsoluteFilePathMatcher,
 } from '@docusaurus/utils';
-import {LoadContext, Plugin, RouteConfig} from '@docusaurus/types';
+import {LoadContext, Plugin} from '@docusaurus/types';
 import {loadSidebars} from './sidebars';
 import {CategoryMetadataFilenamePattern} from './sidebars/generator';
 import {readVersionDocs, processDocMetadata, handleNavigation} from './docs';
@@ -31,7 +31,6 @@ import {
   LoadedContent,
   SourceToPermalink,
   DocMetadataBase,
-  DocMetadata,
   GlobalPluginData,
   VersionMetadata,
   LoadedVersion,
@@ -44,14 +43,15 @@ import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
 import {keyBy, mapValues} from 'lodash';
 import {toGlobalDataVersion} from './globalData';
-import {toTagDocListProp, toVersionMetadataProp} from './props';
+import {toTagDocListProp} from './props';
 import {
   translateLoadedContent,
   getLoadedContentTranslationFiles,
 } from './translations';
 import chalk from 'chalk';
 import {getVersionTags} from './tags';
 import {PropTagsListPage} from '@docusaurus/plugin-content-docs-types';
+import {createVersionRoutes} from './routes';
 
 export default function pluginContentDocs(
   context: LoadContext,
@@ -212,42 +212,10 @@ export default function pluginContentDocs(
       const {docLayoutComponent, docItemComponent} = options;
       const {addRoute, createData, setGlobalData} = actions;
 
-      const createDocRoutes = async (
-        docs: DocMetadata[],
-      ): Promise<RouteConfig[]> => {
-        const routes = await Promise.all(
-          docs.map(async (metadataItem) => {
-            await createData(
-              // Note that this created data path must be in sync with
-              // metadataPath provided to mdx-loader.
-              `${docuHash(metadataItem.source)}.json`,
-              JSON.stringify(metadataItem, null, 2),
-            );
-
-            const docRoute: RouteConfig = {
-              path: metadataItem.permalink,
-              component: docItemComponent,
-              exact: true,
-              modules: {
-                content: metadataItem.source,
-              },
-              // Because the parent (DocPage) comp need to access it easily
-              // This permits to render the sidebar once without unmount/remount when navigating (and preserve sidebar state)
-              ...(metadataItem.sidebar && {
-                sidebar: metadataItem.sidebar,
-              }),
-            };
-
-            return docRoute;
-          }),
-        );
-
-        return routes.sort((a, b) => a.path.localeCompare(b.path));
-      };
-
-      async function createVersionTagsRoutes(loadedVersion: LoadedVersion) {
-        const versionTags = getVersionTags(loadedVersion.docs);
+      async function createVersionTagsRoutes(version: LoadedVersion) {
+        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,
@@ -260,11 +228,11 @@ export default function pluginContentDocs(
           // Only create /tags page if there are tags.
           if (Object.keys(tagsProp).length > 0) {
             const tagsPropPath = await createData(
-              `${docuHash(`tags-list-${loadedVersion.versionName}-prop`)}.json`,
+              `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
               JSON.stringify(tagsProp, null, 2),
             );
             addRoute({
-              path: loadedVersion.tagsPath,
+              path: version.tagsPath,
               exact: true,
               component: options.docTagsListComponent,
               modules: {
@@ -274,11 +242,12 @@ export default function pluginContentDocs(
           }
         }
 
+        // TODO tags should be a sub route of the version route
         async function createTagDocListPage(tag: VersionTag) {
           const tagProps = toTagDocListProp({
-            allTagsPath: loadedVersion.tagsPath,
+            allTagsPath: version.tagsPath,
             tag,
-            docs: loadedVersion.docs,
+            docs: version.docs,
           });
           const tagPropPath = await createData(
             `${docuHash(`tag-${tag.permalink}`)}.json`,
@@ -298,50 +267,21 @@ export default function pluginContentDocs(
         await Promise.all(Object.values(versionTags).map(createTagDocListPage));
       }
 
-      async function doCreateVersionRoutes(
-        loadedVersion: LoadedVersion,
-      ): Promise<void> {
-        await createVersionTagsRoutes(loadedVersion);
-
-        const versionMetadata = toVersionMetadataProp(pluginId, loadedVersion);
-        const versionMetadataPropPath = await createData(
-          `${docuHash(
-            `version-${loadedVersion.versionName}-metadata-prop`,
-          )}.json`,
-          JSON.stringify(versionMetadata, null, 2),
-        );
-
-        addRoute({
-          path: loadedVersion.versionPath,
-          // allow matching /docs/* as well
-          exact: false,
-          // main docs component (DocPage)
-          component: docLayoutComponent,
-          // sub-routes for each doc
-          routes: await createDocRoutes(loadedVersion.docs),
-          modules: {
-            versionMetadata: aliasedSource(versionMetadataPropPath),
-          },
-          priority: loadedVersion.routePriority,
-        });
-      }
-
-      async function createVersionRoutes(
-        loadedVersion: LoadedVersion,
-      ): Promise<void> {
-        try {
-          return await doCreateVersionRoutes(loadedVersion);
-        } catch (e) {
-          console.error(
-            chalk.red(
-              `Can't create version routes for version "${loadedVersion.versionName}"`,
-            ),
-          );
-          throw e;
-        }
-      }
+      await Promise.all(
+        loadedVersions.map((loadedVersion) =>
+          createVersionRoutes({
+            loadedVersion,
+            docItemComponent,
+            docLayoutComponent,
+            pluginId,
+            aliasedSource,
+            actions,
+          }),
+        ),
+      );
 
-      await Promise.all(loadedVersions.map(createVersionRoutes));
+      // TODO tags should be a sub route of the version route
+      await Promise.all(loadedVersions.map(createVersionTagsRoutes));
 
       setGlobalData<GlobalPluginData>({
         path: normalizeUrl([baseUrl, options.routeBasePath]),

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -30,10 +30,17 @@ declare module '@docusaurus/plugin-content-docs-types' {
     docsSidebars: PropSidebars;
   };
 
+  export type PropCategoryGeneratedIndex = {
+    label: string;
+    slug: string;
+    permalink: string;
+  };
+
   export type PropSidebarItemLink = import('./sidebars/types').SidebarItemLink;
   export type PropSidebarItemCategory =
     import('./sidebars/types').PropSidebarItemCategory;
   export type PropSidebarItem = import('./sidebars/types').PropSidebarItem;
+  export type PropSidebar = import('./sidebars/types').PropSidebar;
   export type PropSidebars = import('./sidebars/types').PropSidebars;
 
   export type PropTagDocListDoc = {
@@ -115,6 +122,16 @@ declare module '@theme/DocItem' {
   export default DocItem;
 }
 
+declare module '@theme/DocCategoryGeneratedIndex' {
+  import type {PropCategoryGeneratedIndex} from '@docusaurus/plugin-content-docs-types';
+
+  export interface Props {
+    categoryIndex: PropCategoryGeneratedIndex;
+  }
+
+  export default function DocCategoryGeneratedIndex(props: Props): JSX.Element;
+}
+
 declare module '@theme/DocItemFooter' {
   import type {Props} from '@theme/DocItem';
 

packages/docusaurus-plugin-content-docs/src/props.ts

@@ -10,11 +10,14 @@ import type {
   SidebarItemDoc,
   SidebarItemLink,
   SidebarItem,
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
 } from './sidebars/types';
 import type {
   PropSidebars,
   PropVersionMetadata,
   PropSidebarItem,
+  PropSidebarItemCategory,
   PropTagDocList,
   PropTagDocListDoc,
 } from '@docusaurus/plugin-content-docs-types';
@@ -23,8 +26,7 @@ import {compact, keyBy, mapValues} from 'lodash';
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
   const docsById = keyBy(loadedVersion.docs, (doc) => doc.id);
 
-  const convertDocLink = (item: SidebarItemDoc): SidebarItemLink => {
-    const docId = item.id;
+  function getDocById(docId: string): DocMetadata {
     const docMetadata = docsById[docId];
 
     if (!docMetadata) {
@@ -34,13 +36,16 @@ Available document ids are:
 - ${Object.keys(docsById).sort().join('\n- ')}`,
       );
     }
+    return docMetadata;
+  }
 
+  const convertDocLink = (item: SidebarItemDoc): SidebarItemLink => {
+    const docMetadata = getDocById(item.id);
     const {
       title,
       permalink,
       frontMatter: {sidebar_label: sidebarLabel},
     } = docMetadata;
-
     return {
       type: 'link',
       label: sidebarLabel || item.label || title,
@@ -50,18 +55,37 @@ Available document ids are:
     };
   };
 
-  const normalizeItem = (item: SidebarItem): PropSidebarItem => {
+  function getCategoryLinkHref(
+    link: SidebarItemCategoryLink | undefined,
+  ): string | undefined {
+    switch (link?.type) {
+      case 'doc':
+        return getDocById(link.id).permalink;
+      case 'generated-index':
+        return link.permalink;
+      default:
+        return undefined;
+    }
+  }
+
+  function convertCategory(item: SidebarItemCategory): PropSidebarItemCategory {
+    const {link, ...rest} = item;
+    const href = getCategoryLinkHref(link);
+    return {...rest, items: item.items.map(normalizeItem), ...(href && {href})};
+  }
+
+  function normalizeItem(item: SidebarItem): PropSidebarItem {
     switch (item.type) {
       case 'category':
-        return {...item, items: item.items.map(normalizeItem)};
+        return convertCategory(item);
       case 'ref':
       case 'doc':
         return convertDocLink(item);
       case 'link':
       default:
         return item;
     }
-  };
+  }
 
   // Transform the sidebar so that all sidebar item will be in the
   // form of 'link' or 'category' only.