feat(content-docs): autogenerate category with linked doc metadata as fallback (#6859)

packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap

@@ -1407,6 +1407,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 0,
       "source": "@site/docs/3-API/01_Core APIs/0 --- Client API.md",
       "sourceDirName": "3-API/01_Core APIs",
+      "title": "Client API",
       "unversionedId": "API/Core APIs/Client API",
     },
     {
@@ -1415,6 +1416,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 1,
       "source": "@site/docs/3-API/01_Core APIs/1 --- Server API.md",
       "sourceDirName": "3-API/01_Core APIs",
+      "title": "Server API",
       "unversionedId": "API/Core APIs/Server API",
     },
     {
@@ -1423,6 +1425,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 0,
       "source": "@site/docs/3-API/02_Extension APIs/0. Plugin API.md",
       "sourceDirName": "3-API/02_Extension APIs",
+      "title": "Plugin API",
       "unversionedId": "API/Extension APIs/Plugin API",
     },
     {
@@ -1431,6 +1434,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 1,
       "source": "@site/docs/3-API/02_Extension APIs/1. Theme API.md",
       "sourceDirName": "3-API/02_Extension APIs",
+      "title": "Theme API",
       "unversionedId": "API/Extension APIs/Theme API",
     },
     {
@@ -1439,6 +1443,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 3,
       "source": "@site/docs/3-API/03_api-end.md",
       "sourceDirName": "3-API",
+      "title": "API End",
       "unversionedId": "API/api-end",
     },
     {
@@ -1447,6 +1452,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 0,
       "source": "@site/docs/3-API/00_api-overview.md",
       "sourceDirName": "3-API",
+      "title": "API Overview",
       "unversionedId": "API/api-overview",
     },
     {
@@ -1458,6 +1464,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 1,
       "source": "@site/docs/Guides/z-guide1.md",
       "sourceDirName": "Guides",
+      "title": "Guide 1",
       "unversionedId": "Guides/guide1",
     },
     {
@@ -1468,6 +1475,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 2,
       "source": "@site/docs/Guides/02-guide2.md",
       "sourceDirName": "Guides",
+      "title": "Guide 2",
       "unversionedId": "Guides/guide2",
     },
     {
@@ -1479,6 +1487,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 2.5,
       "source": "@site/docs/Guides/0-guide2.5.md",
       "sourceDirName": "Guides",
+      "title": "Guide 2.5",
       "unversionedId": "Guides/guide2.5",
     },
     {
@@ -1490,6 +1499,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 3,
       "source": "@site/docs/Guides/guide3.md",
       "sourceDirName": "Guides",
+      "title": "Guide 3",
       "unversionedId": "Guides/guide3",
     },
     {
@@ -1500,6 +1510,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": undefined,
       "source": "@site/docs/Guides/a-guide4.md",
       "sourceDirName": "Guides",
+      "title": "Guide 4",
       "unversionedId": "Guides/guide4",
     },
     {
@@ -1510,6 +1521,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": undefined,
       "source": "@site/docs/Guides/b-guide5.md",
       "sourceDirName": "Guides",
+      "title": "Guide 5",
       "unversionedId": "Guides/guide5",
     },
     {
@@ -1518,6 +1530,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 0,
       "source": "@site/docs/0-getting-started.md",
       "sourceDirName": ".",
+      "title": "Getting Started",
       "unversionedId": "getting-started",
     },
     {
@@ -1526,6 +1539,7 @@ exports[`site with custom sidebar items generator sidebarItemsGenerator is calle
       "sidebarPosition": 1,
       "source": "@site/docs/1-installation.md",
       "sourceDirName": ".",
+      "title": "Installation",
       "unversionedId": "installation",
     },
   ],

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap

@@ -116,7 +116,7 @@ exports[`DefaultSidebarItemsGenerator generates subfolder sidebar 1`] = `
         "type": "doc",
       },
     ],
-    "label": "subsubsubfolder3 (_category_.json label)",
+    "label": "Subsubsubfolder category label",
     "link": {
       "id": "doc1",
       "type": "doc",

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts

@@ -234,7 +234,7 @@ describe('DefaultSidebarItemsGenerator', () => {
         },
         'subfolder/subsubfolder/subsubsubfolder3': {
           position: 1,
-          label: 'subsubsubfolder3 (_category_.json label)',
+          // This item's label is defined from the index doc instead
           link: {
             type: 'doc',
             id: 'doc1', // This is a "fully-qualified" ID that can't be found locally
@@ -246,6 +246,7 @@ describe('DefaultSidebarItemsGenerator', () => {
           id: 'doc1',
           source: 'doc1.md',
           sourceDirName: 'subfolder/subsubfolder',
+          title: 'Subsubsubfolder category label',
           sidebarPosition: undefined,
           frontMatter: {},
         },

packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts

@@ -158,9 +158,6 @@ Available doc IDs:
     ): WithPosition<NormalizedSidebarItemCategory> {
       const categoryMetadata =
         categoriesMetadata[posixPath(path.join(autogenDir, fullPath))];
-      const className = categoryMetadata?.className;
-      const customProps = categoryMetadata?.customProps;
-      const {filename, numberPrefix} = numberPrefixParser(folderName);
       const allItems = Object.entries(dir).map(([key, content]) =>
         dirToItem(content, key, `${fullPath}/${key}`),
       );
@@ -184,41 +181,65 @@ Available doc IDs:
         });
       }
 
-      function getCategoryLinkedDocId(): string | undefined {
+      // In addition to the ID, this function also retrieves metadata of the
-        const link = categoryMetadata?.link;
+      // linked doc that could be used as fallback values for category metadata
-        if (link !== undefined) {
+      function getCategoryLinkedDocMetadata():
-          if (link && link.type === 'doc') {
+        | {
-            return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
+            id: string;
+            position?: number;
+            label?: string;
+            customProps?: {[key: string]: unknown};
+            className?: string;
           }
+        | undefined {
+        const link = categoryMetadata?.link;
+        if (link !== undefined && link?.type !== 'doc') {
           // If a link is explicitly specified, we won't apply conventions
           return undefined;
         }
-        // Apply default convention to pick index.md, README.md or
+        const id = link
-        // <categoryName>.md as the category doc
+          ? findDocByLocalId(link.id)?.id ?? getDoc(link.id).id
-        return findConventionalCategoryDocLink()?.id;
+          : findConventionalCategoryDocLink()?.id;
+        if (!id) {
+          return undefined;
+        }
+        const doc = getDoc(id);
+        return {
+          id,
+          position: doc.sidebarPosition,
+          label: doc.frontMatter.sidebar_label ?? doc.title,
+          customProps: doc.frontMatter.sidebar_custom_props,
+          className: doc.frontMatter.sidebar_class_name,
+        };
       }
-
+      const categoryLinkedDoc = getCategoryLinkedDocMetadata();
-      const categoryLinkedDocId = getCategoryLinkedDocId();
-
       const link: SidebarItemCategoryLinkConfig | null | undefined =
-        categoryLinkedDocId
+        categoryLinkedDoc
           ? {
               type: 'doc',
-              id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
+              id: categoryLinkedDoc.id, // We "remap" a potentially "local id" to a "qualified id"
             }
           : categoryMetadata?.link;
-
       // If a doc is linked, remove it from the category subItems
       const items = allItems.filter(
-        (item) => !(item.type === 'doc' && item.id === categoryLinkedDocId),
+        (item) => !(item.type === 'doc' && item.id === categoryLinkedDoc?.id),
       );
 
+      const className =
+        categoryMetadata?.className ?? categoryLinkedDoc?.className;
+      const customProps =
+        categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
+      const {filename, numberPrefix} = numberPrefixParser(folderName);
+
       return {
         type: 'category',
-        label: categoryMetadata?.label ?? filename,
+        label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
         collapsible: categoryMetadata?.collapsible,
         collapsed: categoryMetadata?.collapsed,
-        position: categoryMetadata?.position ?? numberPrefix,
+        position:
+          categoryMetadata?.position ??
+          categoryLinkedDoc?.position ??
+          numberPrefix,
         source: folderName,
         ...(customProps !== undefined && {customProps}),
         ...(className !== undefined && {className}),

packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts

@@ -31,6 +31,7 @@ function toSidebarItemsGeneratorDoc(
   return _.pick(doc, [
     'id',
     'unversionedId',
+    'title',
     'frontMatter',
     'source',
     'sourceDirName',

packages/docusaurus-plugin-content-docs/src/sidebars/types.ts

@@ -231,6 +231,7 @@ export type SidebarItemsGeneratorDoc = Pick<
   DocMetadataBase,
   | 'id'
   | 'unversionedId'
+  | 'title'
   | 'frontMatter'
   | 'source'
   | 'sourceDirName'

website/docs/api/plugins/plugin-content-docs.md

@@ -89,6 +89,7 @@ type SidebarGenerator = (generatorArgs: {
   version: {contentPath: string; versionName: string}; // the current version
   docs: Array<{
     id: string;
+    title: string;
     frontMatter: DocFrontMatter & Record<string, unknown>;
     source: string;
     sourceDirName: string;

website/docs/guides/docs/sidebar/autogenerated.md

@@ -323,7 +323,7 @@ sidebar_class_name: green
 This is the easy tutorial!
 ```
 
-**For categories**: add a `_category_.json` or `_category_.yml` file in the respective folder. You can specify any category metadata and also the `position` metadata.
+**For categories**: add a `_category_.json` or `_category_.yml` file in the respective folder. You can specify any category metadata and also the `position` metadata. `label`, `className`, `position`, and `customProps` will default to the respective values of the category's linked doc, if there is one.
 
 <Tabs>
 <TabItem value="JSON">