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

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

@@ -5,11 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {normalizeUrl} from '@docusaurus/utils';
+import {Sidebar} from './sidebars/types';
+import {getFirstDocIdOfSidebar} from './sidebars/utils';
 import type {
   DocMetadata,
   GlobalDoc,
   LoadedVersion,
   GlobalVersion,
+  GlobalSidebar,
 } from './types';
 
 export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
@@ -20,13 +24,44 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
+export function toGlobalSidebar(
+  sidebarId: string,
+  sidebar: Sidebar,
+  version: LoadedVersion,
+): GlobalSidebar {
+  const sidebarFirstDocId = getFirstDocIdOfSidebar(sidebar);
+  let sidebarFirstDocPermalink;
+  if (!sidebarFirstDocId.isAutoGeneratedIndex) {
+    sidebarFirstDocPermalink = version.docs.find(
+      (doc) => doc.id === sidebarFirstDocId.firstDocId,
+    )?.permalink;
+  } else {
+    sidebarFirstDocPermalink = normalizeUrl([
+      version.versionPath,
+      sidebarFirstDocId.firstDocId,
+    ]);
+  }
+  return {
+    link: {
+      label: sidebarId,
+      path: sidebarFirstDocPermalink ?? sidebarFirstDocId.firstDocId,
+    },
+  };
+}
+
 export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
+  const globalSidebarRecord: Record<string, GlobalSidebar> = {};
+  Object.entries(version.sidebars).forEach(([sidebarId, sidebar]) => {
+    const globalSidebarObject = toGlobalSidebar(sidebarId, sidebar, version);
+    globalSidebarRecord[sidebarId] = globalSidebarObject;
+  });
   return {
     name: version.versionName,
     label: version.versionLabel,
     isLast: version.isLast,
     path: version.versionPath,
     mainDocId: version.mainDocId,
     docs: version.docs.map(toGlobalDataDoc),
+    sidebars: globalSidebarRecord,
   };
 }

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

@@ -327,3 +327,37 @@ export function toNavigationLink(
     throw new Error('unexpected navigation item');
   }
 }
+
+export function getFirstDocIdOfSidebar(sidebar: Sidebar): {
+  isAutoGeneratedIndex: boolean;
+  firstDocId: string;
+} {
+  const firstSidebarItem = sidebar[0];
+  let firstDocId = '';
+  let isAutoGeneratedIndex = false;
+  if (firstSidebarItem.type === 'doc' || firstSidebarItem.type === 'ref') {
+    firstDocId = firstSidebarItem.id;
+  } else if (firstSidebarItem.type === 'link') {
+    firstDocId = firstSidebarItem.href;
+  } else if (firstSidebarItem.type === 'category') {
+    const firstCategoryLink = firstSidebarItem.link;
+    if (firstCategoryLink) {
+      if (firstCategoryLink.type === 'doc') {
+        firstDocId = firstCategoryLink.id;
+      } else if (firstCategoryLink.type === 'generated-index') {
+        isAutoGeneratedIndex = true;
+        firstDocId = firstCategoryLink.slug;
+      }
+    } else {
+      const childSidebarItemFirstDocId = getFirstDocIdOfSidebar([
+        firstSidebarItem.items[0],
+      ]);
+      firstDocId = childSidebarItemFirstDocId.firstDocId;
+      isAutoGeneratedIndex = childSidebarItemFirstDocId.isAutoGeneratedIndex;
+    }
+  }
+  return {
+    isAutoGeneratedIndex,
+    firstDocId,
+  };
+}

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

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

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

@@ -477,10 +477,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 id: 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';
@@ -490,7 +503,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,72 @@
+/**
+ * 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) {
+    const sidebarIds = Object.keys(allSidebars).join('\n- ');
+    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:\n- ${sidebarIds}`,
+    );
+  }
+  if (sidebar.link && sidebar.link.path) {
+    return sidebar.link;
+  }
+  throw new Error(
+    `DocSidebarNavbarItem: couldn't find a path for sidebar with id "${sidebarId}"`,
+  );
+}
+
+export default function DocSidebarNavbarItem({
+  id,
+  label: staticLabel,
+  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, id);
+  const activeDocInfimaClassName = getInfimaActiveClassName(props.mobile);
+
+  return (
+    <DefaultNavbarItem
+      exact
+      {...props}
+      className={clsx(props.className, {
+        [activeDocInfimaClassName]:
+          activeDoc?.sidebar && activeDoc.sidebar === id,
+      })}
+      activeClassName={activeDocInfimaClassName}
+      label={staticLabel ?? sidebarLink.label ?? sidebarLink.label}
+      to={sidebarLink.path}
+    />
+  );
+}

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

@@ -32,6 +32,7 @@ const NavbarItemComponents: Record<
   docsVersionDropdown: () =>
     require('@theme/NavbarItem/DocsVersionDropdownNavbarItem').default,
   doc: () => require('@theme/NavbarItem/DocNavbarItem').default,
+  docSidebar: () => require('@theme/NavbarItem/DocSidebarNavbarItem').default,
   /* eslint-enable @typescript-eslint/no-var-requires, global-require */
 } as const;
 

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

@@ -85,6 +85,12 @@ const DocItemSchema = NavbarItemBaseSchema.append({
   docsPluginId: Joi.string(),
 });
 
+const DocSidebarItemSchema = NavbarItemBaseSchema.append({
+  type: Joi.string().equal('docSidebar').required(),
+  id: Joi.string().required(),
+  docsPluginId: Joi.string(),
+});
+
 const itemWithType = (type: string | undefined) => {
   // because equal(undefined) is not supported :/
   const typeSchema = type
@@ -172,6 +178,10 @@ const NavbarItemSchema = Joi.object({
       is: itemWithType('doc'),
       then: DocItemSchema,
     },
+    {
+      is: itemWithType('docSidebar'),
+      then: DocSidebarItemSchema,
+    },
     {
       is: itemWithType('localeDropdown'),
       then: LocaleDropdownNavbarItemSchema,