diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js index 402803c0c4..975f1203fe 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-category.js @@ -9,25 +9,30 @@ module.exports = { docs: [ { type: 'category', + collapsed: true, label: 'level 1', items: [ 'a', { type: 'category', + collapsed: true, label: 'level 2', items: [ { type: 'category', + collapsed: true, label: 'level 3', items: [ 'c', { type: 'category', + collapsed: true, label: 'level 4', items: [ 'd', { type: 'category', + collapsed: true, label: 'deeper more more', items: ['e'], }, diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json new file mode 100644 index 0000000000..1251a7d454 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json @@ -0,0 +1,20 @@ +{ + "docs": [ + { + "type": "category", + "label": "Introduction", + "items": [ + "doc1" + ], + "collapsed": false + }, + { + "type": "category", + "label": "Powering MDX", + "items": [ + "doc2" + ], + "collapsed": false + } + ] +} \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed.json b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed.json new file mode 100644 index 0000000000..2199c5f557 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/sidebars/sidebars-collapsed.json @@ -0,0 +1,21 @@ +{ + "docs": { + "Test": [ + { + "type": "category", + "label": "Introduction", + "items": ["doc1"], + "collapsed": false + } + ], + "Reference": [ + { + "type": "category", + "label": "Powering MDX", + "items": ["doc2"], + "collapsed": false + } + ] + } + } + \ No newline at end of file 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 11d22b0c99..dd85d4c264 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 @@ -4,6 +4,7 @@ exports[`simple website content 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "items": Array [ @@ -36,6 +37,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/hello", @@ -200,6 +202,7 @@ exports[`versioned website content: all sidebars 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/next/foo/bar", @@ -211,6 +214,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/next/hello", @@ -224,6 +228,7 @@ Object { ], "version-1.0.0/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/1.0.0/foo/bar", @@ -240,6 +245,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/1.0.0/hello", @@ -253,6 +259,7 @@ Object { ], "version-1.0.1/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/foo/bar", @@ -264,6 +271,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/hello", @@ -283,6 +291,7 @@ Object { "docsSidebars": Object { "version-1.0.0/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/1.0.0/foo/bar", @@ -299,6 +308,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/1.0.0/hello", @@ -325,6 +335,7 @@ Object { "docsSidebars": Object { "version-1.0.1/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/foo/bar", @@ -336,6 +347,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/hello", @@ -361,6 +373,7 @@ Object { "docsSidebars": Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/next/foo/bar", @@ -372,6 +385,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "href": "/docs/next/hello", diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap index e0bc01bdc9..0aa670c44b 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/sidebars.test.ts.snap @@ -4,6 +4,7 @@ exports[`loadSidebars sidebars link 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "href": "https://github.com", @@ -18,30 +19,107 @@ Object { } `; +exports[`loadSidebars sidebars with category.collapsed property 1`] = ` +Object { + "docs": Array [ + Object { + "collapsed": true, + "items": Array [ + Object { + "collapsed": false, + "items": Array [ + Object { + "id": "doc1", + "type": "doc", + }, + ], + "label": "Introduction", + "type": "category", + }, + ], + "label": "Test", + "type": "category", + }, + Object { + "collapsed": true, + "items": Array [ + Object { + "collapsed": false, + "items": Array [ + Object { + "id": "doc2", + "type": "doc", + }, + ], + "label": "Powering MDX", + "type": "category", + }, + ], + "label": "Reference", + "type": "category", + }, + ], +} +`; + +exports[`loadSidebars sidebars with category.collapsed property at first level 1`] = ` +Object { + "docs": Array [ + Object { + "collapsed": false, + "items": Array [ + Object { + "id": "doc1", + "type": "doc", + }, + ], + "label": "Introduction", + "type": "category", + }, + Object { + "collapsed": false, + "items": Array [ + Object { + "id": "doc2", + "type": "doc", + }, + ], + "label": "Powering MDX", + "type": "category", + }, + ], +} +`; + exports[`loadSidebars sidebars with deep level of category 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "id": "a", "type": "doc", }, Object { + "collapsed": true, "items": Array [ Object { + "collapsed": true, "items": Array [ Object { "id": "c", "type": "doc", }, Object { + "collapsed": true, "items": Array [ Object { "id": "d", "type": "doc", }, Object { + "collapsed": true, "items": Array [ Object { "id": "e", @@ -100,6 +178,7 @@ exports[`loadSidebars sidebars with known sidebar item type 1`] = ` Object { "docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "id": "foo/bar", @@ -123,6 +202,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "id": "hello", diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/version.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/version.test.ts.snap index 47ffaef77f..26c10f3c0a 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/version.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/version.test.ts.snap @@ -4,6 +4,7 @@ exports[`docsVersion first time versioning 1`] = ` Object { "version-1.0.0/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "items": Array [ @@ -33,6 +34,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "id": "version-1.0.0/hello", @@ -50,6 +52,7 @@ exports[`docsVersion not the first time versioning 1`] = ` Object { "version-2.0.0/docs": Array [ Object { + "collapsed": true, "items": Array [ Object { "id": "version-2.0.0/foo/bar", @@ -60,6 +63,7 @@ Object { "type": "category", }, Object { + "collapsed": true, "items": Array [ Object { "id": "version-2.0.0/hello", diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts index 49a788dfd9..11d882b22a 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts @@ -126,4 +126,19 @@ describe('loadSidebars', () => { const result = loadSidebars(null); expect(result).toEqual({}); }); + + test('sidebars with category.collapsed property', async () => { + const sidebarPath = path.join(fixtureDir, 'sidebars-collapsed.json'); + const result = loadSidebars([sidebarPath]); + expect(result).toMatchSnapshot(); + }); + + test('sidebars with category.collapsed property at first level', async () => { + const sidebarPath = path.join( + fixtureDir, + 'sidebars-collapsed-first-level.json', + ); + const result = loadSidebars([sidebarPath]); + expect(result).toMatchSnapshot(); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars.ts b/packages/docusaurus-plugin-content-docs/src/sidebars.ts index cfe1b36254..abe988984b 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars.ts @@ -33,6 +33,7 @@ function normalizeCategoryShorthand( ): SidebarItemCategoryRaw[] { return Object.entries(sidebar).map(([label, items]) => ({ type: 'category', + collapsed: true, label, items, })); @@ -56,7 +57,7 @@ function assertItem(item: Object, keys: string[]): void { } function assertIsCategory(item: any): asserts item is SidebarItemCategoryRaw { - assertItem(item, ['items', 'label']); + assertItem(item, ['items', 'label', 'collapsed']); if (typeof item.label !== 'string') { throw new Error( `Error loading ${JSON.stringify(item)}. "label" must be a string.`, @@ -67,6 +68,12 @@ function assertIsCategory(item: any): asserts item is SidebarItemCategoryRaw { `Error loading ${JSON.stringify(item)}. "items" must be an array.`, ); } + // "collapsed" is an optional property + if (item.hasOwnProperty('collapsed') && typeof item.collapsed !== 'boolean') { + throw new Error( + `Error loading ${JSON.stringify(item)}. "collapsed" must be a boolean.`, + ); + } } function assertIsDoc(item: any): asserts item is SidebarItemDoc { diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 4929797c59..9516cec3f7 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -40,12 +40,14 @@ export interface SidebarItemCategory { type: 'category'; label: string; items: SidebarItem[]; + collapsed?: boolean; } export interface SidebarItemCategoryRaw { type: 'category'; label: string; items: SidebarItemRaw[]; + collapsed?: boolean; } export type SidebarItem = @@ -81,6 +83,7 @@ export interface DocsSidebarItemCategory { type: 'category'; label: string; items: DocsSidebarItem[]; + collapsed?: boolean; } export type DocsSidebarItem = SidebarItemLink | DocsSidebarItemCategory; diff --git a/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js b/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js index c59c3611f4..29bdfa2b70 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js +++ b/packages/docusaurus-theme-classic/src/theme/DocSidebar/index.js @@ -105,8 +105,11 @@ function mutateSidebarCollapsingState(item, path) { items .map((childItem) => mutateSidebarCollapsingState(childItem, path)) .filter((val) => val).length > 0; - // eslint-disable-next-line no-param-reassign - item.collapsed = !anyChildItemsActive; + // only modify item.collapsed if there are child items active and the category collapsed is set to true + if (anyChildItemsActive && item.collapsed) { + // eslint-disable-next-line no-param-reassign + item.collapsed = !anyChildItemsActive; + } return anyChildItemsActive; } diff --git a/website/docs/docs.md b/website/docs/docs.md index d44c89ebed..b46a67309f 100644 --- a/website/docs/docs.md +++ b/website/docs/docs.md @@ -207,6 +207,7 @@ type SidebarItemCategory = { type: 'category'; label: string; // Sidebar label text. items: SidebarItem[]; // Array of sidebar items. + collapsed: boolean; // Set the category to be collapsed or open by default }; ```