feat(theme-classic): new navbar item linking to a sidebar

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

@@ -323,6 +323,14 @@ Object {
           "mainDocId": "hello",
           "name": "current",
           "path": "/docs",
+          "sidebars": Object {
+            "docs": Object {
+              "link": Object {
+                "label": "foo/bar",
+                "path": "/docs/foo/bar",
+              },
+            },
+          },
         },
       ],
     },
@@ -1007,6 +1015,14 @@ Object {
           "mainDocId": "hello",
           "name": "current",
           "path": "/docs",
+          "sidebars": Object {
+            "docs": Object {
+              "link": Object {
+                "label": "foo/bar",
+                "path": "/docs/foo/bar",
+              },
+            },
+          },
         },
       ],
     },
@@ -2359,6 +2375,14 @@ Object {
           "mainDocId": "team",
           "name": "current",
           "path": "/community/next",
+          "sidebars": Object {
+            "community": Object {
+              "link": Object {
+                "label": "team",
+                "path": "/community/next/team",
+              },
+            },
+          },
         },
         Object {
           "docs": Array [
@@ -2373,6 +2397,14 @@ Object {
           "mainDocId": "team",
           "name": "1.0.0",
           "path": "/community",
+          "sidebars": Object {
+            "version-1.0.0/community": Object {
+              "link": Object {
+                "label": "version-1.0.0/team",
+                "path": "/community/team",
+              },
+            },
+          },
         },
       ],
     },
@@ -3407,6 +3439,14 @@ Object {
           "mainDocId": "hello",
           "name": "current",
           "path": "/docs/next",
+          "sidebars": Object {
+            "docs": Object {
+              "link": Object {
+                "label": "foo/bar",
+                "path": "/docs/next/foo/barSlug",
+              },
+            },
+          },
         },
         Object {
           "docs": Array [
@@ -3426,6 +3466,14 @@ Object {
           "mainDocId": "hello",
           "name": "1.0.1",
           "path": "/docs",
+          "sidebars": Object {
+            "VersionedSideBarNameDoesNotMatter/docs": Object {
+              "link": Object {
+                "label": "foo/bar",
+                "path": "/docs/foo/bar",
+              },
+            },
+          },
         },
         Object {
           "docs": Array [
@@ -3450,6 +3498,14 @@ Object {
           "mainDocId": "hello",
           "name": "1.0.0",
           "path": "/docs/1.0.0",
+          "sidebars": Object {
+            "version-1.0.0/docs": Object {
+              "link": Object {
+                "label": "version-1.0.0/foo/bar",
+                "path": "/docs/1.0.0/foo/barSlug",
+              },
+            },
+          },
         },
         Object {
           "docs": Array [
@@ -3499,6 +3555,14 @@ Object {
           "mainDocId": "rootAbsoluteSlug",
           "name": "withSlugs",
           "path": "/docs/withSlugs",
+          "sidebars": Object {
+            "version-1.0.1/docs": Object {
+              "link": Object {
+                "label": "version-withSlugs/rootAbsoluteSlug",
+                "path": "/docs/withSlugs/rootAbsoluteSlug",
+              },
+            },
+          },
         },
       ],
     },

packages/docusaurus-plugin-content-docs/src/globalData.ts

@@ -5,11 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {mapValues} from 'lodash';
+import {normalizeUrl} from '@docusaurus/utils';
+import type {Sidebars} from './sidebars/types';
+import {createSidebarsUtils} from './sidebars/utils';
 import type {
   DocMetadata,
   GlobalDoc,
   LoadedVersion,
   GlobalVersion,
+  GlobalSidebar,
 } from './types';
 
 export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
@@ -20,6 +25,31 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
+export function toGlobalSidebars(
+  sidebars: Sidebars,
+  version: LoadedVersion,
+): Record<string, GlobalSidebar> {
+  const {getFirstLink} = createSidebarsUtils(sidebars);
+  return mapValues(sidebars, (sidebar, sidebarId) => {
+    const firstLink = getFirstLink(sidebarId);
+    if (!firstLink) {
+      return {};
+    }
+    return {
+      link: {
+        path:
+          firstLink.type === 'generated-index'
+            ? normalizeUrl([version.versionPath, firstLink.slug])
+            : version.docs.find(
+                (doc) =>
+                  doc.id === firstLink.id || doc.unversionedId === firstLink.id,
+              )!.permalink,
+        label: firstLink.label,
+      },
+    };
+  });
+}
+
 export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
   return {
     name: version.versionName,
@@ -28,5 +58,6 @@ export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
     path: version.versionPath,
     mainDocId: version.mainDocId,
     docs: version.docs.map(toGlobalDataDoc),
+    sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -11,9 +11,10 @@ declare module '@docusaurus/plugin-content-docs' {
   export type VersionBanner = import('./types').VersionBanner;
   type GlobalDataVersion = import('./types').GlobalVersion;
   type GlobalDataDoc = import('./types').GlobalDoc;
+  type GlobalDataSidebar = import('./types').GlobalSidebar;
   type VersionTag = import('./types').VersionTag;
 
-  export type {GlobalDataVersion, GlobalDataDoc};
+  export type {GlobalDataVersion, GlobalDataDoc, GlobalDataSidebar};
 
   export type PropNavigationLink = {
     readonly title: string;

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

@@ -46,7 +46,7 @@ describe('createSidebarsUtils', () => {
       collapsible: true,
       label: 'S2 Category',
       items: [
-        {type: 'doc', id: 'doc3'},
+        {type: 'doc', id: 'doc3', label: 'Doc 3'},
         {type: 'doc', id: 'doc4'},
       ],
     },
@@ -95,14 +95,33 @@ describe('createSidebarsUtils', () => {
     },
   ];
 
-  const sidebars: Sidebars = {sidebar1, sidebar2, sidebar3};
+  const sidebar4: Sidebar = [
+    {
+      type: 'category',
+      collapsed: false,
+      collapsible: true,
+      label: 'S4 Category',
+      link: {
+        type: 'generated-index',
+        slug: '/s4-category-slug',
+        permalink: '/s4-category-permalink',
+      },
+      items: [
+        {type: 'doc', id: 'doc8'},
+        {type: 'doc', id: 'doc9'},
+      ],
+    },
+  ];
+
+  const sidebars: Sidebars = {sidebar1, sidebar2, sidebar3, sidebar4};
 
   const {
     getFirstDocIdOfFirstSidebar,
     getSidebarNameByDocId,
     getDocNavigation,
     getCategoryGeneratedIndexNavigation,
     getCategoryGeneratedIndexList,
+    getFirstLink,
   } = createSidebarsUtils(sidebars);
 
   test('getSidebarNameByDocId', async () => {
@@ -121,15 +140,15 @@ describe('createSidebarsUtils', () => {
   });
 
   test('getDocNavigation', async () => {
-    expect(getDocNavigation('doc1')).toEqual({
+    expect(getDocNavigation('doc1', 'doc1')).toEqual({
       sidebarName: 'sidebar1',
       previous: undefined,
       next: {
         type: 'doc',
         id: 'doc2',
       },
     } as SidebarNavigation);
-    expect(getDocNavigation('doc2')).toEqual({
+    expect(getDocNavigation('doc2', 'doc2')).toEqual({
       sidebarName: 'sidebar1',
       previous: {
         type: 'doc',
@@ -138,32 +157,33 @@ describe('createSidebarsUtils', () => {
       next: undefined,
     } as SidebarNavigation);
 
-    expect(getDocNavigation('doc3')).toEqual({
+    expect(getDocNavigation('doc3', 'doc3')).toEqual({
       sidebarName: 'sidebar2',
       previous: undefined,
       next: {
         type: 'doc',
         id: 'doc4',
       },
     } as SidebarNavigation);
-    expect(getDocNavigation('doc4')).toEqual({
+    expect(getDocNavigation('doc4', 'doc4')).toEqual({
       sidebarName: 'sidebar2',
       previous: {
         type: 'doc',
         id: 'doc3',
+        label: 'Doc 3',
       },
       next: undefined,
     } as SidebarNavigation);
 
-    expect(getDocNavigation('doc5')).toMatchObject({
+    expect(getDocNavigation('doc5', 'doc5')).toMatchObject({
       sidebarName: 'sidebar3',
       previous: undefined,
       next: {
         type: 'category',
         label: 'S3 SubCategory',
       },
     } as SidebarNavigation);
-    expect(getDocNavigation('doc6')).toMatchObject({
+    expect(getDocNavigation('doc6', 'doc6')).toMatchObject({
       sidebarName: 'sidebar3',
       previous: {
         type: 'category',
@@ -174,7 +194,7 @@ describe('createSidebarsUtils', () => {
         id: 'doc7',
       },
     } as SidebarNavigation);
-    expect(getDocNavigation('doc7')).toMatchObject({
+    expect(getDocNavigation('doc7', 'doc7')).toMatchObject({
       sidebarName: 'sidebar3',
       previous: {
         type: 'doc',
@@ -224,8 +244,35 @@ describe('createSidebarsUtils', () => {
         type: 'category',
         label: 'S3 SubSubCategory',
       },
+      {
+        type: 'category',
+        label: 'S4 Category',
+      },
     ]);
   });
+
+  test('getFirstLink', () => {
+    expect(getFirstLink('sidebar1')).toEqual({
+      id: 'doc1',
+      type: 'doc',
+      label: 'doc1',
+    });
+    expect(getFirstLink('sidebar2')).toEqual({
+      id: 'doc3',
+      type: 'doc',
+      label: 'Doc 3',
+    });
+    expect(getFirstLink('sidebar3')).toEqual({
+      id: 'doc5',
+      type: 'doc',
+      label: 'S3 Category',
+    });
+    expect(getFirstLink('sidebar4')).toEqual({
+      type: 'generated-index',
+      slug: '/s4-category-slug',
+      label: 'S4 Category',
+    });
+  });
 });
 
 describe('collectSidebarDocItems', () => {