diff --git 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 index 3c40354723..44346d589b 100644 --- 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", }, ], diff --git 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 index 3ab94d6010..e042c36658 100644 --- 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", diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts index 501774ef60..66281f746b 100644 --- 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: {}, }, diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts index 5e266bc005..928731fc4f 100644 --- 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 { 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 - // .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}), diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/processor.ts index 7e5fa5b6a5..a4f55b6bf5 100644 --- 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', diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 8ad3c310b7..50a1e6185c 100644 --- 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' diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index 2c97cd4ab7..cf69f8f8a2 100644 --- 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; source: string; sourceDirName: string; diff --git a/website/docs/guides/docs/sidebar/autogenerated.md b/website/docs/guides/docs/sidebar/autogenerated.md index 0b74e1f61f..239888b99f 100644 --- 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.