From 1698957e81a1fc410f52ea0ca5b02c89230f7359 Mon Sep 17 00:00:00 2001 From: taejs Date: Sat, 5 Mar 2022 17:39:51 +0900 Subject: [PATCH 1/3] feat(content-docs): allow custom props through _category_.json --- .../src/__tests__/__snapshots__/docs.test.ts.snap | 2 ++ .../src/__tests__/__snapshots__/index.test.ts.snap | 10 ++++++++++ .../__tests__/__snapshots__/index.test.ts.snap | 1 + .../src/sidebars/generator.ts | 1 + .../src/sidebars/types.ts | 1 + .../src/sidebars/validation.ts | 1 + 6 files changed, 16 insertions(+) diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap index b66f4a4929c5..9a610f7daa96 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap @@ -166,6 +166,7 @@ Object { Object { "collapsed": false, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "foo/bar", @@ -216,6 +217,7 @@ Object { Object { "collapsed": false, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "slugs/absoluteSlug", 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 3fb1a48e0a71..6277798ad240 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 @@ -1268,6 +1268,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "API/api-end", @@ -1276,6 +1277,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "API/Extension APIs/Theme API", @@ -1293,6 +1295,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "API/Core APIs/Server API", @@ -1319,6 +1322,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "Guides/guide5", @@ -1964,6 +1968,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "Guides/guide1", @@ -1997,6 +2002,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "API/api-overview", @@ -2005,6 +2011,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "API/Core APIs/Client API", @@ -2022,6 +2029,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "API/Extension APIs/Plugin API", @@ -2063,6 +2071,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "API/Core APIs/Client API", @@ -2080,6 +2089,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "API/Extension APIs/Plugin API", diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/index.test.ts.snap index ed1a6911deab..e9b47af59119 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/index.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/index.test.ts.snap @@ -253,6 +253,7 @@ Object { Object { "collapsed": true, "collapsible": true, + "customProps": undefined, "items": Array [ Object { "id": "bar", diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts index 811e0923094d..5422b9a5d1ff 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts @@ -219,6 +219,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({ collapsed: categoryMetadata?.collapsed, position: categoryMetadata?.position ?? numberPrefix, source: folderName, + customProps: categoryMetadata?.customProps, ...(className !== undefined && {className}), items, ...(link && {link}), diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 914a854b6389..f9f6895ec96b 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -216,6 +216,7 @@ export type CategoryMetadataFile = { collapsible?: boolean; className?: string; link?: SidebarItemCategoryLinkConfig | null; + customProps?: Record; // TODO should we allow "items" here? how would this work? would an // "autogenerated" type be allowed? diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts index 76dfb7ec1857..9ee2115e131c 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts @@ -164,6 +164,7 @@ const categoryMetadataFileSchema = Joi.object({ collapsible: Joi.boolean(), className: Joi.string(), link: sidebarItemCategoryLinkSchema, + customProps: Joi.object().unknown(), }); export function validateCategoryMetadataFile( From 6f633191d8f5a808d65da4732d55f9155bb94c4a Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sat, 5 Mar 2022 18:37:25 +0800 Subject: [PATCH 2/3] refactor --- .../src/__tests__/__snapshots__/docs.test.ts.snap | 2 -- .../src/__tests__/__snapshots__/index.test.ts.snap | 10 ---------- .../__tests__/__snapshots__/index.test.ts.snap | 1 - .../src/sidebars/__tests__/generator.test.ts | 10 +++++++++- .../src/sidebars/generator.ts | 3 ++- 5 files changed, 11 insertions(+), 15 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap index 9a610f7daa96..b66f4a4929c5 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/docs.test.ts.snap @@ -166,7 +166,6 @@ Object { Object { "collapsed": false, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "foo/bar", @@ -217,7 +216,6 @@ Object { Object { "collapsed": false, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "slugs/absoluteSlug", 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 6277798ad240..3fb1a48e0a71 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 @@ -1268,7 +1268,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "API/api-end", @@ -1277,7 +1276,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "API/Extension APIs/Theme API", @@ -1295,7 +1293,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "API/Core APIs/Server API", @@ -1322,7 +1319,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "Guides/guide5", @@ -1968,7 +1964,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "Guides/guide1", @@ -2002,7 +1997,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "API/api-overview", @@ -2011,7 +2005,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "API/Core APIs/Client API", @@ -2029,7 +2022,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "API/Extension APIs/Plugin API", @@ -2071,7 +2063,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "API/Core APIs/Client API", @@ -2089,7 +2080,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "API/Extension APIs/Plugin API", diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/index.test.ts.snap index e9b47af59119..ed1a6911deab 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/index.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/index.test.ts.snap @@ -253,7 +253,6 @@ Object { Object { "collapsed": true, "collapsible": true, - "customProps": undefined, "items": Array [ Object { "id": "bar", 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 61f7ba4ab4b7..d45cdc842540 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 @@ -126,7 +126,12 @@ describe('DefaultSidebarItemsGenerator', () => { contentPath: '', }, categoriesMetadata: { - '02-Guides': {collapsed: false}, + '02-Guides': { + collapsed: false, + customProps: { + description: 'foo', + }, + }, '02-Guides/01-SubGuides': { label: 'SubGuides (metadata file label)', link: { @@ -230,6 +235,9 @@ describe('DefaultSidebarItemsGenerator', () => { type: 'doc', id: 'guides-index', }, + customProps: { + description: 'foo', + }, collapsed: false, items: [ {type: 'doc', id: 'guide1', className: 'foo'}, diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts index 5422b9a5d1ff..9d6b4c3d394a 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts @@ -159,6 +159,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({ 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}`), @@ -219,7 +220,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({ collapsed: categoryMetadata?.collapsed, position: categoryMetadata?.position ?? numberPrefix, source: folderName, - customProps: categoryMetadata?.customProps, + ...(customProps !== undefined && {customProps}), ...(className !== undefined && {className}), items, ...(link && {link}), From 50d52ee080e7a35d91d7b3a0b500d1ab39820315 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sat, 5 Mar 2022 18:39:13 +0800 Subject: [PATCH 3/3] documentation --- website/docs/guides/docs/sidebar/autogenerated.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/website/docs/guides/docs/sidebar/autogenerated.md b/website/docs/guides/docs/sidebar/autogenerated.md index 807de81571de..0b74e1f61faa 100644 --- a/website/docs/guides/docs/sidebar/autogenerated.md +++ b/website/docs/guides/docs/sidebar/autogenerated.md @@ -338,6 +338,9 @@ This is the easy tutorial! "link": { "type": "generated-index", "title": "Tutorial overview" + }, + "customProps": { + "description": "This description can be used in the swizzled DocCard" } } ``` @@ -354,6 +357,8 @@ className: red link: type: generated-index title: Tutorial overview +customProps: + description: This description can be used in the swizzled DocCard ```