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

2025-05-03 12:17:20 +02:00 · 2022-03-25 22:23:11 +08:00 · 2022-03-25 22:23:11 +08:00 · b5ceead3b2
commit b5ceead3b2
parent f1bcdbff63
8 changed files with 62 additions and 23 deletions
--- a/packages/docusaurus-plugin-content-docs/src/tests/snapshots/index.test.ts.snap
+++ b/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",
    },
  ],
--- a/packages/docusaurus-plugin-content-docs/src/sidebars/tests/snapshots/generator.test.ts.snap
+++ b/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",
--- a/packages/docusaurus-plugin-content-docs/src/sidebars/tests/generator.test.ts
+++ b/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: {},
        },
--- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts
+++ b/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 {
-        const link = categoryMetadata?.link;
-        if (link !== undefined) {
-          if (link && link.type === 'doc') {
-            return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
+      // In addition to the ID, this function also retrieves metadata of the
+      // linked doc that could be used as fallback values for category metadata
+      function getCategoryLinkedDocMetadata():
+        | {
+            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
-        // <categoryName>.md as the category doc
-        return findConventionalCategoryDocLink()?.id;
+        const id = link
+          ? findDocByLocalId(link.id)?.id ?? getDoc(link.id).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 categoryLinkedDocId = getCategoryLinkedDocId();
-
+      const categoryLinkedDoc = getCategoryLinkedDocMetadata();
      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}),
--- a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts
+++ b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts
@ -31,6 +31,7 @@ function toSidebarItemsGeneratorDoc(
  return _.pick(doc, [
    'id',
    'unversionedId',
+    'title',
    'frontMatter',
    'source',
    'sourceDirName',
--- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts
+++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts
@ -231,6 +231,7 @@ export type SidebarItemsGeneratorDoc = Pick<
  DocMetadataBase,
  | 'id'
  | 'unversionedId'
+  | 'title'
  | 'frontMatter'
  | 'source'
  | 'sourceDirName'
--- a/website/docs/api/plugins/plugin-content-docs.md
+++ b/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;
--- a/website/docs/guides/docs/sidebar/autogenerated.md
+++ b/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">