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,11 @@ Object {
           "mainDocId": "hello",
           "name": "current",
           "path": "/docs",
+          "sidebars": Object {
+            "docs": Object {
+              "link": "/docs/foo/bar",
+            },
+          },
         },
       ],
     },
@@ -1007,6 +1012,11 @@ Object {
           "mainDocId": "hello",
           "name": "current",
           "path": "/docs",
+          "sidebars": Object {
+            "docs": Object {
+              "link": "/docs/foo/bar",
+            },
+          },
         },
       ],
     },
@@ -2359,6 +2369,11 @@ Object {
           "mainDocId": "team",
           "name": "current",
           "path": "/community/next",
+          "sidebars": Object {
+            "community": Object {
+              "link": "/community/next/team",
+            },
+          },
         },
         Object {
           "docs": Array [
@@ -2373,6 +2388,11 @@ Object {
           "mainDocId": "team",
           "name": "1.0.0",
           "path": "/community",
+          "sidebars": Object {
+            "version-1.0.0/community": Object {
+              "link": "/community/team",
+            },
+          },
         },
       ],
     },
@@ -3407,6 +3427,11 @@ Object {
           "mainDocId": "hello",
           "name": "current",
           "path": "/docs/next",
+          "sidebars": Object {
+            "docs": Object {
+              "link": "/docs/next/foo/barSlug",
+            },
+          },
         },
         Object {
           "docs": Array [
@@ -3426,6 +3451,11 @@ Object {
           "mainDocId": "hello",
           "name": "1.0.1",
           "path": "/docs",
+          "sidebars": Object {
+            "VersionedSideBarNameDoesNotMatter/docs": Object {
+              "link": "/docs/foo/bar",
+            },
+          },
         },
         Object {
           "docs": Array [
@@ -3450,6 +3480,11 @@ Object {
           "mainDocId": "hello",
           "name": "1.0.0",
           "path": "/docs/1.0.0",
+          "sidebars": Object {
+            "version-1.0.0/docs": Object {
+              "link": "/docs/1.0.0/foo/barSlug",
+            },
+          },
         },
         Object {
           "docs": Array [
@@ -3499,6 +3534,11 @@ Object {
           "mainDocId": "rootAbsoluteSlug",
           "name": "withSlugs",
           "path": "/docs/withSlugs",
+          "sidebars": Object {
+            "version-1.0.1/docs": Object {
+              "link": "/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,29 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
+export function toGlobalSidebars(
+  sidebars: Sidebars,
+  version: LoadedVersion,
+): Record<string, GlobalSidebar> {
+  const {getFirstDocOfSidebar} = createSidebarsUtils(sidebars);
+  return mapValues(sidebars, (sidebar, sidebarId) => {
+    const firstDoc = getFirstDocOfSidebar(sidebarId);
+    if (!firstDoc) {
+      throw new Error(
+        `The sidebar "${sidebarId}" doesn't seem to contain any documentation`,
+      );
+    }
+    return {
+      link: firstDoc.isAutoGeneratedIndex
+        ? normalizeUrl([version.versionPath, firstDoc.slug])
+        : version.docs.find(
+            (doc) =>
+              doc.id === firstDoc.id || doc.unversionedId === firstDoc.id,
+          )!.permalink,
+    };
+  });
+}
+
 export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
   return {
     name: version.versionName,
@@ -28,5 +56,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/sidebars/__tests__/utils.test.ts

@@ -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,
+    getFirstDocOfSidebar,
   } = createSidebarsUtils(sidebars);
 
   test('getSidebarNameByDocId', async () => {
@@ -224,8 +243,28 @@ describe('createSidebarsUtils', () => {
         type: 'category',
         label: 'S3 SubSubCategory',
       },
+      {
+        type: 'category',
+        label: 'S4 Category',
+      },
     ]);
   });
+
+  test('getFirstDocOfSidebar', async () => {
+    expect(getFirstDocOfSidebar('sidebar1')).toMatchObject({
+      id: 'doc1',
+    });
+    expect(getFirstDocOfSidebar('sidebar2')).toMatchObject({
+      id: 'doc3',
+    });
+    expect(getFirstDocOfSidebar('sidebar3')).toMatchObject({
+      id: 'doc5',
+    });
+    expect(getFirstDocOfSidebar('sidebar4')).toMatchObject({
+      isAutoGeneratedIndex: true,
+      slug: '/s4-category-slug',
+    });
+  });
 });
 
 describe('collectSidebarDocItems', () => {

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

@@ -138,6 +138,16 @@ export type SidebarsUtils = {
   getCategoryGeneratedIndexNavigation: (
     categoryGeneratedIndexPermalink: string,
   ) => SidebarNavigation;
+  getFirstDocOfSidebar: (sidebarId: string) =>
+    | {
+        isAutoGeneratedIndex: false;
+        id: string;
+      }
+    | {
+        isAutoGeneratedIndex: true;
+        slug: string;
+      }
+    | undefined;
 
   checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
 };
@@ -266,6 +276,45 @@ Available document ids are:
     }
   }
 
+  function getFirstDocOfSidebar(sidebar: Sidebar):
+    | {
+        isAutoGeneratedIndex: false;
+        id: string;
+      }
+    | {
+        isAutoGeneratedIndex: true;
+        slug: string;
+      }
+    | undefined {
+    // eslint-disable-next-line no-restricted-syntax
+    for (const item of sidebar) {
+      if (item.type === 'doc') {
+        return {
+          isAutoGeneratedIndex: false,
+          id: item.id,
+        };
+      } else if (item.type === 'category') {
+        if (item.link?.type === 'doc') {
+          return {
+            isAutoGeneratedIndex: false,
+            id: item.link.id,
+          };
+        } else if (item.link?.type === 'generated-index') {
+          return {
+            isAutoGeneratedIndex: true,
+            slug: item.link.slug,
+          };
+        } else {
+          const doc = getFirstDocOfSidebar(item.items);
+          if (doc) {
+            return doc;
+          }
+        }
+      }
+    }
+    return undefined;
+  }
+
   return {
     sidebars,
     getFirstDocIdOfFirstSidebar,
@@ -274,6 +323,7 @@ Available document ids are:
     getCategoryGeneratedIndexList,
     getCategoryGeneratedIndexNavigation,
     checkSidebarsDocIds,
+    getFirstDocOfSidebar: (id) => getFirstDocOfSidebar(sidebars[id]),
   };
 }
 

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

@@ -214,6 +214,12 @@ export type GlobalVersion = {
   path: string;
   mainDocId: string; // home doc (if docs homepage configured), or first doc
   docs: GlobalDoc[];
+  sidebars?: Record<string, GlobalSidebar>;
+};
+
+export type GlobalSidebar = {
+  link: string;
+  // ... we may add other things here later
 };
 
 export type GlobalPluginData = {

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -488,10 +488,23 @@ declare module '@theme/NavbarItem/DocNavbarItem' {
   export default DocsSidebarNavbarItem;
 }
 
+declare module '@theme/NavbarItem/DocSidebarNavbarItem' {
+  import type {Props as DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
+
+  export interface Props extends DefaultNavbarItemProps {
+    readonly sidebarId: string;
+    readonly docsPluginId?: string;
+  }
+
+  const DocSidebarNavbarItem: (props: Props) => JSX.Element;
+  export default DocSidebarNavbarItem;
+}
+
 declare module '@theme/NavbarItem' {
   import type {ComponentProps} from 'react';
   import type {Props as DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
   import type {Props as DocNavbarItemProps} from '@theme/NavbarItem/DocNavbarItem';
+  import type {Props as DocSidebarNavbarItemProps} from '@theme/NavbarItem/DocSidebarNavbarItem';
   import type {Props as DocsVersionNavbarItemProps} from '@theme/NavbarItem/DocsVersionNavbarItem';
   import type {Props as DropdownNavbarItemProps} from '@theme/NavbarItem/DropdownNavbarItem';
   import type {Props as DocsVersionDropdownNavbarItemProps} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
@@ -501,7 +514,8 @@ declare module '@theme/NavbarItem' {
   export type LinkLikeNavbarItemProps =
     | ({readonly type?: 'default'} & DefaultNavbarItemProps)
     | ({readonly type: 'doc'} & DocNavbarItemProps)
-    | ({readonly type: 'docsVersion'} & DocsVersionNavbarItemProps);
+    | ({readonly type: 'docsVersion'} & DocsVersionNavbarItemProps)
+    | ({readonly type: 'docSidebar'} & DocSidebarNavbarItemProps);
 
   export type Props = ComponentProps<'a'> & {
     readonly position?: 'left' | 'right';

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocSidebarNavbarItem.tsx

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
+import {useLatestVersion, useActiveDocContext} from '@theme/hooks/useDocs';
+import clsx from 'clsx';
+import {getInfimaActiveClassName} from './index';
+import type {Props} from '@theme/NavbarItem/DocSidebarNavbarItem';
+import {useDocsPreferredVersion, uniq} from '@docusaurus/theme-common';
+import type {GlobalDataVersion} from '@docusaurus/plugin-content-docs';
+
+function getSidebarInVersion(versions: GlobalDataVersion[], sidebarId: string) {
+  const allSidebars = versions.map((version) => version.sidebars)[0];
+  if (!allSidebars) {
+    throw new Error(`DocSidebarNavbarItem: couldn't find any sidebar`);
+  }
+  const sidebar = allSidebars[sidebarId];
+  if (!sidebar) {
+    throw new Error(
+      `DocSidebarNavbarItem: couldn't find any sidebar with id "${sidebarId}" in version${
+        versions.length ? 's' : ''
+      } ${versions.map((version) => version.name).join(', ')}".
+Available sidebar ids are:
+- ${Object.keys(allSidebars).join('\n- ')}`,
+    );
+  }
+  return sidebar.link;
+}
+
+export default function DocSidebarNavbarItem({
+  sidebarId,
+  label,
+  docsPluginId,
+  ...props
+}: Props): JSX.Element {
+  const {activeVersion, activeDoc} = useActiveDocContext(docsPluginId);
+  const {preferredVersion} = useDocsPreferredVersion(docsPluginId);
+  const latestVersion = useLatestVersion(docsPluginId);
+
+  // Versions used to look for the doc to link to, ordered + no duplicate
+  const versions = uniq(
+    [activeVersion, preferredVersion, latestVersion].filter(
+      Boolean,
+    ) as GlobalDataVersion[],
+  );
+  const sidebarLink = getSidebarInVersion(versions, sidebarId);
+  const activeDocInfimaClassName = getInfimaActiveClassName(props.mobile);
+
+  return (
+    <DefaultNavbarItem
+      exact
+      {...props}
+      className={clsx(props.className, {
+        [activeDocInfimaClassName]:
+          activeDoc?.sidebar && activeDoc.sidebar === sidebarId,
+      })}
+      activeClassName={activeDocInfimaClassName}
+      label={label ?? sidebarId}
+      to={sidebarLink}
+    />
+  );
+}