Include sidebar name in breadcrumbs

[ghost]

What does this PR fix/introduce?

Workaround for facebook/docusaurus#6953, to include top-level section in breadcrumbs:

Additionally we detect index-like pages, and hide their breadcrumb:

Closes #1216.

Additional context

Content for DocBreadcrumbs/styles.module.css was copied directly from Docusaurus code.

Content for DocBreadcrumbs/index.tsx is based on https://raw.githubusercontent.com/facebook/docusaurus/v2.4.1/packages/docusaurus-theme-classic/src/theme/DocBreadcrumbs/index.tsx with the following changes:

@@ -1,3 +1,7 @@
+/**
+ * Content is based on https://github.com/facebook/docusaurus/blob/v2.4.1/packages/docusaurus-theme-classic/src/theme/DocBreadcrumbs/index.tsx.
+ * For details see https://github.com/casper-network/docs/issues/1216.
+ /
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
@@ -8,10 +12,11 @@
 import React, { ReactNode } from "react";
 import clsx from "clsx";
 import { ThemeClassNames } from "@docusaurus/theme-common";
-import { useSidebarBreadcrumbs, useHomePageRoute } from "@docusaurus/theme-common/internal";
+import { useSidebarBreadcrumbs, useHomePageRoute, useDoc, useDocsSidebar } from "@docusaurus/theme-common/internal";
 import Link from "@docusaurus/Link";
 import { translate } from "@docusaurus/Translate";
 import HomeBreadcrumbItem from "@theme/DocBreadcrumbs/Items/Home";
+import { PropSidebarBreadcrumbsItem } from "@docusaurus/plugin-content-docs";
 
 import styles from "./styles.module.css";
 
@@ -69,7 +74,7 @@ function BreadcrumbsItem({
 }
 
 export default function DocBreadcrumbs(): JSX.Element | null {
-    const breadcrumbs = useSidebarBreadcrumbs();
+    const breadcrumbs = useEnhancedSidebarBreadcrumbs();
     const homePageRoute = useHomePageRoute();
 
     if (!breadcrumbs) {
@@ -101,3 +106,48 @@ export default function DocBreadcrumbs(): JSX.Element | null {
         </nav>
     );
 }
+
+// Workaround for https://github.com/facebook/docusaurus/issues/6953.
+//
+function useEnhancedSidebarBreadcrumbs(): PropSidebarBreadcrumbsItem[] | null {
+    let breadcrumbs = useSidebarBreadcrumbs();
+    const sidebar = useDocsSidebar();
+
+    if (breadcrumbs === null) {
+        return null;
+    }
+
+    if (sidebar === null || sidebar.items.length === 0) {
+        return breadcrumbs;
+    }
+
+    // Add breadcrumb with top-level section.
+    //
+    // NOTE: Sidebar is not connected directly with navbar items, so we make simple assumption that for sidebar named "foo_bar" we get:
+    // - Label: "Foo_bar"
+    // - URL: "/foo_bar"
+    // We hope it points to the correct navbar item.
+    const sidebarName = sidebar.name;
+    const label = sidebarName.charAt(0).toUpperCase() + sidebarName.slice(1);
+    const href = "/" + sidebarName;
+    const topLevelBreadcrumb: PropSidebarBreadcrumbsItem = {
+        collapsed: true,
+        collapsible: true,
+        href,
+        items: [],
+        label,
+        type: "category",
+    };
+    breadcrumbs.unshift(topLevelBreadcrumb);
+
+    // Remove last breadcrumb if we detect index-like page.
+    //
+    // NOTE: Detection is based on assumption that index page will be a first link in the sidebar.
+    const firstSidebarItem = sidebar.items[0];
+    const lastBreadcrumb = breadcrumbs.at(-1);
+    if (firstSidebarItem.type === "link" && lastBreadcrumb.type === "link" && firstSidebarItem.docId === lastBreadcrumb.docId) {
+        breadcrumbs.pop();
+    }
+
+    return breadcrumbs;
+}

Checklist

• Docs are successfully building - yarn install && yarn run build.
• All technical procedures have been tested.

[ipopescu]

I want to test this after PR #1217 merges. I can approve this based on testing, since I don't have experience with the docusaurus updates.

[ghost]

TODO: merge with the latest dev and remove breadcrumb TODOs introduced by #1217.

[ipopescu]

I merged with the latest dev to do some testing. Navigation works as expected.

There is a bit of a strange situation though when we are on the index page of these major categories. We see the category and the title on the index page. Is it possible to remove the title from the crumbs:

This happens only on these pages:

• operators/index
• resources/index
• developers/index
• concepts/index
• users/index

If it's not possible, I would take the current behavior over what we had before.

[ghost]

@ipopescu It is possible, although I had to make assumption that index page is the first item in the sidebar: https://github.com/casper-network/docs/pull/1219/files#diff-f0a13f8874197a80b860a20dab0030153554d0704e80691fa05ecd31dda8ce97R143-R150

Please try the updated version 😉, IMO it works great.

[ipopescu]

@andrzej-casper this is awesome, thanks! IMO, assuming the index page is the first item in the sidebar is a sound assumption.

[wilhelmer]

Thank you for this, I also implemented that in our docs.

Just a quick note that you can improve the code by looking up the sidebar ID in the theme config, and then get the actual navbar label from there.

So instead of

const label = sidebarName.charAt(0).toUpperCase() + sidebarName.slice(1);

you can do:

import { useThemeConfig } from '@docusaurus/theme-common';
[...]
const {
  navbar: {items: navbarItems},
} = useThemeConfig();
const label = navbarItems.find((item) => item.sidebarId === sidebar.name)?.label || "";