Breadcrumb links to all pages, category indexes

config/navbar.config.ts

@@ -1,8 +1,8 @@
-import {Navbar} from "@docusaurus/theme-common";
+import { Navbar } from "@docusaurus/theme-common";
 
-const navbar: Omit<Navbar, "style"> = { // don't specify style here, we want it to be dynamic
+// don't specify style or hideOnScroll here, we want it to be dynamic
+const navbar: Omit<Navbar, "style" | "hideOnScroll"> = {
   title: "PaperMC Docs",
-  hideOnScroll: true,
   logo: {
     src: "img/logo.svg",
     alt: "PaperMC Logo",

config/sidebars.config.ts

@@ -3,9 +3,20 @@ import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
 const sidebars: SidebarsConfig = {
   docs: [
     {
-      type: "link",
-      label: "Support Discord",
-      href: "https://discord.gg/papermc",
+      type: "category",
+      label: "Getting Help",
+      items: [
+        {
+          type: "link",
+          label: "Discord",
+          href: "https://discord.gg/papermc",
+        },
+        {
+          type: "link",
+          label: "Forums",
+          href: "https://forums.papermc.io",
+        },
+      ],
     },
     "README",
     {
@@ -32,6 +43,10 @@ const sidebars: SidebarsConfig = {
         {
           type: "category",
           label: "How-to Guides",
+          link: {
+            type: "generated-index",
+            slug: "/category/paper/how-to-guides",
+          },
           items: [
             "paper/how-to/per-world-configuration",
             "paper/how-to/anti-xray",
@@ -42,6 +57,10 @@ const sidebars: SidebarsConfig = {
         {
           type: "category",
           label: "Reference",
+          link: {
+            type: "generated-index",
+            slug: "/category/paper/reference",
+          },
           items: [
             "paper/reference/paper-global-configuration",
             "paper/reference/paper-per-world-configuration",
@@ -74,6 +93,10 @@ const sidebars: SidebarsConfig = {
         {
           type: "category",
           label: "How-to Guides",
+          link: {
+            type: "generated-index",
+            slug: "/category/velocity/how-to-guides",
+          },
           items: [
             "velocity/how-to/security",
             "velocity/how-to/tuning",
@@ -83,6 +106,10 @@ const sidebars: SidebarsConfig = {
         {
           type: "category",
           label: "Reference",
+          link: {
+            type: "generated-index",
+            slug: "/category/velocity/reference",
+          },
           items: [
             "velocity/reference/configuration",
             "velocity/reference/commands",
@@ -103,6 +130,10 @@ const sidebars: SidebarsConfig = {
             {
               type: "category",
               label: "Getting Started",
+              link: {
+                type: "generated-index",
+                slug: "/category/velocity/developers/getting-started",
+              },
               items: [
                 "velocity/developers/getting-started/creating-your-first-plugin",
                 "velocity/developers/getting-started/api-basics",
@@ -112,6 +143,10 @@ const sidebars: SidebarsConfig = {
             {
               type: "category",
               label: "How-to Guides",
+              link: {
+                type: "generated-index",
+                slug: "/category/velocity/developers/how-to-guides",
+              },
               items: [
                 "velocity/developers/how-to/dependencies",
                 "velocity/developers/how-to/porting-from-velocity-1",
@@ -120,6 +155,10 @@ const sidebars: SidebarsConfig = {
             {
               type: "category",
               label: "API",
+              link: {
+                type: "generated-index",
+                slug: "/category/velocity/developers/api",
+              },
               items: [
                 "velocity/developers/api/event",
                 "velocity/developers/api/command",
@@ -142,11 +181,21 @@ const sidebars: SidebarsConfig = {
     {
       type: "category",
       label: "Common",
+      link: {
+        type: "generated-index",
+        slug: "/category/common",
+        description: "Documentation relevant to all PaperMC projects.",
+      },
       items: ["common/java-install"],
     },
     {
       type: "category",
       label: "PaperMC",
+      link: {
+        type: "generated-index",
+        slug: "/category/papermc",
+        description: "Information about the PaperMC Organization.",
+      },
       items: ["papermc/downloads-api", "papermc/assets", "papermc/contact"],
     },
   ],

docusaurus.config.ts

@@ -28,6 +28,7 @@ const config: Config = {
   projectName: "docs",
   trailingSlash: false,
   noIndex: isPreview,
+  baseUrlIssueBanner: false,
 
   webpack: {
     jsLoader: (isServer) => ({

src/theme/DocBreadcrumbs/index.tsx

@@ -0,0 +1,87 @@
+import React, { type ReactNode } from "react";
+import { ThemeClassNames, useSidebarBreadcrumbs, useHomePageRoute } 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 = "breadcrumbs__link";
+  return href ? (
+    <Link className={className} href={href} itemProp="item">
+      <span itemProp="name">{children}</span>
+    </Link>
+  ) : (
+    <span className={className} itemProp="item name">
+      {children}
+    </span>
+  );
+}
+
+// TODO move to design system folder
+function BreadcrumbsItem({
+  children,
+  active,
+  index,
+}: {
+  children: ReactNode;
+  active?: boolean;
+  index: number;
+}): JSX.Element {
+  return (
+    <li
+      itemScope
+      itemProp="itemListElement"
+      itemType="https://schema.org/ListItem"
+      className={clsx("breadcrumbs__item", {
+        "breadcrumbs__item--active": active,
+      })}
+    >
+      {children}
+      <meta itemProp="position" content={String(index + 1)} />
+    </li>
+  );
+}
+
+function HomeBreadcrumbItem() {
+  const homeHref = useBaseUrl("/");
+  return (
+    <li className="breadcrumbs__item">
+      <Link className={clsx("breadcrumbs__link", styles.breadcrumbsItemLink)} href={homeHref}>
+        🏠
+      </Link>
+    </li>
+  );
+}
+
+export default function DocBreadcrumbs(): JSX.Element | null {
+  const breadcrumbs = useSidebarBreadcrumbs();
+  const homePageRoute = useHomePageRoute();
+
+  if (!breadcrumbs) {
+    return null;
+  }
+
+  return (
+    <nav
+      className={clsx(ThemeClassNames.docs.docBreadcrumbs, styles.breadcrumbsContainer)}
+      aria-label="breadcrumbs"
+    >
+      <ul className="breadcrumbs" itemScope itemType="https://schema.org/BreadcrumbList">
+        {homePageRoute && <HomeBreadcrumbItem />}
+        {breadcrumbs.map((item, idx) => (
+          <BreadcrumbsItem key={idx} active={idx === breadcrumbs.length - 1} index={idx}>
+            <BreadcrumbsItemLink href={item.href}> {item.label}</BreadcrumbsItemLink>
+          </BreadcrumbsItem>
+        ))}
+      </ul>
+    </nav>
+  );
+}

src/theme/DocBreadcrumbs/styles.module.css

@@ -0,0 +1,4 @@
+.breadcrumbsContainer {
+  --ifm-breadcrumb-size-multiplier: 0.8;
+  margin-bottom: 0.8rem;
+}