feat(docs,theme-classic): docs breadcrumbs (#6517)

Co-authored-by: sebastienlorber <[email protected]>

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

@@ -242,6 +242,7 @@ exports[`simple website content 5`] = `
 Object {
   "pluginName": Object {
     "pluginId": Object {
+      "breadcrumbs": true,
       "path": "/docs",
       "versions": Array [
         Object {
@@ -955,6 +956,7 @@ exports[`simple website content: global data 1`] = `
 Object {
   "pluginName": Object {
     "pluginId": Object {
+      "breadcrumbs": true,
       "path": "/docs",
       "versions": Array [
         Object {
@@ -2411,6 +2413,7 @@ exports[`versioned website (community) content: global data 1`] = `
 Object {
   "pluginName": Object {
     "pluginId": Object {
+      "breadcrumbs": true,
       "path": "/community",
       "versions": Array [
         Object {
@@ -3450,6 +3453,7 @@ exports[`versioned website content: global data 1`] = `
 Object {
   "pluginName": Object {
     "pluginId": Object {
+      "breadcrumbs": true,
       "path": "/docs",
       "versions": Array [
         Object {

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

@@ -56,6 +56,7 @@ describe('normalizeDocsPluginOptions', () => {
       rehypePlugins: [markdownPluginsFunctionStub],
       beforeDefaultRehypePlugins: [],
       beforeDefaultRemarkPlugins: [],
+      breadcrumbs: true,
       showLastUpdateTime: true,
       showLastUpdateAuthor: true,
       admonitions: {},

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

@@ -217,6 +217,7 @@ export default async function pluginContentDocs(
         docLayoutComponent,
         docItemComponent,
         docCategoryGeneratedIndexComponent,
+        breadcrumbs,
       } = options;
       const {addRoute, createData, setGlobalData} = actions;
 
@@ -295,6 +296,7 @@ export default async function pluginContentDocs(
       setGlobalData<GlobalPluginData>({
         path: normalizeUrl([baseUrl, options.routeBasePath]),
         versions: loadedVersions.map(toGlobalDataVersion),
+        breadcrumbs,
       });
     },
 

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

@@ -55,6 +55,7 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   editLocalizedFiles: false,
   sidebarCollapsible: true,
   sidebarCollapsed: true,
+  breadcrumbs: true,
 };
 
 const VersionOptionsSchema = Joi.object({
@@ -139,6 +140,7 @@ export const OptionsSchema = Joi.object({
   disableVersioning: Joi.bool().default(DEFAULT_OPTIONS.disableVersioning),
   lastVersion: Joi.string().optional(),
   versions: VersionsOptionsSchema,
+  breadcrumbs: Joi.bool().default(DEFAULT_OPTIONS.breadcrumbs),
 });
 
 export function validateOptions({

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

@@ -38,6 +38,7 @@ declare module '@docusaurus/plugin-content-docs' {
     showLastUpdateTime?: boolean;
     showLastUpdateAuthor?: boolean;
     numberPrefixParser: NumberPrefixParser;
+    breadcrumbs: boolean;
   };
 
   export type PathOptions = {
@@ -126,6 +127,8 @@ declare module '@docusaurus/plugin-content-docs' {
   export type PropSidebarItemCategory =
     import('./sidebars/types').PropSidebarItemCategory;
   export type PropSidebarItem = import('./sidebars/types').PropSidebarItem;
+  export type PropSidebarBreadcrumbsItem =
+    import('./sidebars/types').PropSidebarBreadcrumbsItem;
   export type PropSidebar = import('./sidebars/types').PropSidebar;
   export type PropSidebars = import('./sidebars/types').PropSidebars;
 
@@ -237,6 +240,10 @@ declare module '@theme/DocTagDocListPage' {
   export default function DocTagDocListPage(props: Props): JSX.Element;
 }
 
+declare module '@theme/DocBreadcrumbs' {
+  export default function DocBreadcrumbs(): JSX.Element;
+}
+
 declare module '@theme/DocPage' {
   import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
   import type {DocumentRoute} from '@theme/DocItem';
@@ -294,6 +301,7 @@ declare module '@docusaurus/plugin-content-docs/client' {
   export type GlobalPluginData = {
     path: string;
     versions: GlobalVersion[];
+    breadcrumbs: boolean;
   };
   export type DocVersionSuggestions = {
     // suggest the latest version

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

@@ -195,6 +195,10 @@ export type PropSidebars = {
   [sidebarId: string]: PropSidebar;
 };
 
+export type PropSidebarBreadcrumbsItem =
+  | PropSidebarItemLink
+  | PropSidebarItemCategory;
+
 export type PropVersionDoc = {
   id: string;
   title: string;

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

@@ -0,0 +1,86 @@
+/**
+ * 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, {type ReactNode} from 'react';
+import {ThemeClassNames, useSidebarBreadcrumbs} from '@docusaurus/theme-common';
+import styles from './styles.module.css';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+// TODO move to design system folder
+function BreadcrumbsItemLink({
+  children,
+  href,
+}: {
+  children: ReactNode;
+  href?: string;
+}): JSX.Element {
+  const className = clsx('breadcrumbs__link', styles.breadcrumbsItemLink);
+  return href ? (
+    <Link className={className} href={href}>
+      {children}
+    </Link>
+  ) : (
+    <span className={className}>{children}</span>
+  );
+}
+
+// TODO move to design system folder
+function BreadcrumbsItem({
+  children,
+  active,
+}: {
+  children: ReactNode;
+  active?: boolean;
+}): JSX.Element {
+  return (
+    <li
+      className={clsx('breadcrumbs__item', {
+        'breadcrumbs__item--active': active,
+      })}>
+      {children}
+    </li>
+  );
+}
+
+function HomeBreadcrumbItem() {
+  const homeHref = useBaseUrl('/');
+  return (
+    <BreadcrumbsItem>
+      <BreadcrumbsItemLink href={homeHref}>🏠</BreadcrumbsItemLink>
+    </BreadcrumbsItem>
+  );
+}
+
+export default function DocBreadcrumbs(): JSX.Element | null {
+  const breadcrumbs = useSidebarBreadcrumbs();
+
+  if (!breadcrumbs) {
+    return null;
+  }
+
+  return (
+    <nav
+      className={clsx(
+        ThemeClassNames.docs.docBreadcrumbs,
+        styles.breadcrumbsContainer,
+      )}
+      aria-label="breadcrumbs">
+      <ul className="breadcrumbs">
+        <HomeBreadcrumbItem />
+        {breadcrumbs.map((item, idx) => (
+          <BreadcrumbsItem key={idx} active={idx === breadcrumbs.length - 1}>
+            <BreadcrumbsItemLink href={item.href}>
+              {item.label}
+            </BreadcrumbsItemLink>
+          </BreadcrumbsItem>
+        ))}
+      </ul>
+    </nav>
+  );
+}

packages/docusaurus-theme-classic/src/theme/DocBreadcrumbs/styles.module.css

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+
+.breadcrumbsContainer {
+  margin-bottom: 0.4rem;
+}
+
+.breadcrumbsItemLink {
+  --ifm-breadcrumb-size-multiplier: 0.7 !important;
+  margin-bottom: 0.4rem;
+  background: var(--ifm-color-gray-100);
+}
+
+html[data-theme='dark'] .breadcrumbsItemLink {
+  background-color: var(--ifm-color-gray-900);
+}
+
+@media (min-width: 997px) {
+  .breadcrumbsItemLink {
+    --ifm-breadcrumb-size-multiplier: 0.8;
+  }
+}

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

@@ -13,6 +13,7 @@ import DocPaginator from '@theme/DocPaginator';
 import Seo from '@theme/Seo';
 import DocVersionBanner from '@theme/DocVersionBanner';
 import DocVersionBadge from '@theme/DocVersionBadge';
+import DocBreadcrumbs from '@theme/DocBreadcrumbs';
 import Heading from '@theme/Heading';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
@@ -33,6 +34,7 @@ export default function DocCategoryGeneratedIndexPage({
       />
       <div className={styles.generatedIndexPage}>
         <DocVersionBanner />
+        <DocBreadcrumbs />
         <DocVersionBadge />
         <header>
           <Heading as="h1" className={styles.title}>

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

@@ -18,6 +18,7 @@ import TOCCollapsible from '@theme/TOCCollapsible';
 import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 import {ThemeClassNames, useWindowSize} from '@docusaurus/theme-common';
+import DocBreadcrumbs from '@theme/DocBreadcrumbs';
 
 export default function DocItem(props: Props): JSX.Element {
   const {content: DocContent} = props;
@@ -58,6 +59,7 @@ export default function DocItem(props: Props): JSX.Element {
           <DocVersionBanner />
           <div className={styles.docItemContainer}>
             <article>
+              <DocBreadcrumbs />
               <DocVersionBadge />
 
               {canRenderTOC && (

packages/docusaurus-theme-common/src/index.ts

@@ -49,6 +49,7 @@ export {
   findFirstCategoryLink,
   useCurrentSidebarCategory,
   isActiveSidebarItem,
+  useSidebarBreadcrumbs,
 } from './utils/docsUtils';
 
 export {isSamePath} from './utils/pathUtils';

packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts

@@ -43,6 +43,7 @@ export const ThemeClassNames = {
   docs: {
     docVersionBanner: 'theme-doc-version-banner',
     docVersionBadge: 'theme-doc-version-badge',
+    docBreadcrumbs: 'theme-doc-breadcrumbs',
     docMarkdown: 'theme-doc-markdown',
     docTocMobile: 'theme-doc-toc-mobile',
     docTocDesktop: 'theme-doc-toc-desktop',