From 96a61a42ece59a9635c4f995942b527e41a759a4 Mon Sep 17 00:00:00 2001
From: Janet Blackquill <uhhadd@gmail.com>
Date: Sun, 21 Apr 2024 14:25:37 -0400
Subject: [PATCH] Flatten the development hierarchy

This makes the content more immediately accessible and easier to browse through.
Styling has also been adjusted as necessary to accomodate a flatter hierarchy of items;
presenting content as a list with headers instead of a grid of cards.
---
 config/sidebar.paper.ts                   | 102 ++++++++++------------
 docs/paper/README.mdx                     |   5 +-
 docs/paper/dev/README.mdx                 |   5 +-
 docs/paper/dev/api/README.mdx             |  11 ---
 docs/paper/dev/getting-started/README.mdx |  11 ---
 docs/paper/dev/misc/README.mdx            |  10 ---
 src/css/custom.css                        |  34 ++++++++
 src/theme/DocCard/index.tsx               |  53 ++++++-----
 src/theme/DocCard/styles.module.css       |  20 ++---
 src/theme/DocCardList/index.tsx           |  27 ++++++
 vercel.json                               |  12 +++
 11 files changed, 165 insertions(+), 125 deletions(-)
 delete mode 100644 docs/paper/dev/api/README.mdx
 delete mode 100644 docs/paper/dev/getting-started/README.mdx
 delete mode 100644 docs/paper/dev/misc/README.mdx
 create mode 100644 src/theme/DocCardList/index.tsx

diff --git a/config/sidebar.paper.ts b/config/sidebar.paper.ts
index 3f19ac758..340293115 100644
--- a/config/sidebar.paper.ts
+++ b/config/sidebar.paper.ts
@@ -6,6 +6,7 @@ const paper: SidebarsConfig = {
     {
       type: "category",
       label: "Administration",
+      description: "Create, configure, and maintain a Paper server.",
       collapsed: true,
       link: {
         type: "doc",
@@ -82,6 +83,7 @@ const paper: SidebarsConfig = {
     {
       type: "category",
       label: "Development",
+      description: "Create plugins with the Paper API in order to extend Minecraft with custom and modified behavior.",
       collapsed: true,
       link: {
         type: "doc",
@@ -89,80 +91,68 @@ const paper: SidebarsConfig = {
       },
       items: [
         {
-          type: "category",
-          label: "Getting started",
-          collapsed: true,
-          link: {
-            type: "doc",
-            id: "dev/getting-started/README",
-          },
-          items: [
-            "dev/getting-started/project-setup",
-            "dev/getting-started/plugin-yml",
-            "dev/getting-started/how-do-plugins-work",
-            "dev/getting-started/paper-plugins",
-            "dev/getting-started/userdev",
-          ],
+          type: "html",
+          value: "Getting Started",
+          className: "sidebarTitle",
+          defaultStyle: true,
+        },
+        "dev/getting-started/project-setup",
+        "dev/getting-started/plugin-yml",
+        "dev/getting-started/how-do-plugins-work",
+        "dev/getting-started/paper-plugins",
+        "dev/getting-started/userdev",
+        {
+          type: "html",
+          value: "Plugin API",
+          className: "sidebarTitle",
+          defaultStyle: true,
         },
         {
           type: "category",
-          label: "API",
+          label: "Event API",
+          description: "Respond to and modify in-game actions",
           collapsed: true,
-          link: {
-            type: "doc",
-            id: "dev/api/README",
-          },
           items: [
-            {
-              type: "category",
-              label: "Event API",
-              collapsed: true,
-              items: [
-                "dev/api/event-api/event-listeners",
-                "dev/api/event-api/custom-events",
-                "dev/api/event-api/handler-lists",
-                "dev/api/event-api/chat-event",
-              ],
-            },
-            {
-              type: "category",
-              label: "Component API (Adventure)",
-              collapsed: true,
-              items: [
-                "dev/api/component-api/intro",
-                "dev/api/component-api/i18n",
-                "dev/api/component-api/audiences",
-              ],
-            },
-            "dev/api/pdc",
-            "dev/api/custom-inventory-holder",
-            "dev/api/scheduler",
-            "dev/api/plugin-messaging",
-            "dev/api/plugin-configs",
-            "dev/api/folia-support",
-            "dev/api/roadmap",
+            "dev/api/event-api/event-listeners",
+            "dev/api/event-api/custom-events",
+            "dev/api/event-api/handler-lists",
+            "dev/api/event-api/chat-event",
           ],
         },
         {
           type: "category",
-          label: "Miscellaneous",
+          label: "Component API (Adventure)",
+          description: "Work with Minecraft's chat components",
           collapsed: true,
-          link: {
-            type: "doc",
-            id: "dev/misc/README",
-          },
           items: [
-            "dev/misc/reading-stacktraces",
-            "dev/misc/debugging",
-            "dev/misc/databases",
-            "dev/misc/internal-code",
+            "dev/api/component-api/intro",
+            "dev/api/component-api/i18n",
+            "dev/api/component-api/audiences",
           ],
         },
+        "dev/api/pdc",
+        "dev/api/custom-inventory-holder",
+        "dev/api/scheduler",
+        "dev/api/plugin-messaging",
+        "dev/api/plugin-configs",
+        "dev/api/folia-support",
+        "dev/api/roadmap",
+        {
+          type: "html",
+          value: "Miscellaneous",
+          className: "sidebarTitle",
+          defaultStyle: true,
+        },
+        "dev/misc/reading-stacktraces",
+        "dev/misc/debugging",
+        "dev/misc/databases",
+        "dev/misc/internal-code",
       ],
     },
     {
       type: "category",
       label: "Contributing",
+      description: "Contribute code changes to the Paper server.",
       collapsed: true,
       link: {
         type: "doc",
diff --git a/docs/paper/README.mdx b/docs/paper/README.mdx
index c3bf58a9f..c9ccebe86 100644
--- a/docs/paper/README.mdx
+++ b/docs/paper/README.mdx
@@ -1,6 +1,6 @@
 import DocCardList from "@theme/DocCardList";
 
-# Welcome to the Paper Docs
+# Paper
 
 Paper is a high performance fork of Spigot that aims to fix gameplay and
 mechanic inconsistencies as well as to improve performance. Paper contains numerous features, bug
@@ -14,17 +14,20 @@ fixes, exploit preventions and major performance improvements not found in Spigo
     "label": "Administration",
     "href": "/paper/admin",
     "customEmoji": "mdi:account-cog",
+    "description": "Create, configure, and maintain a Paper server.",
   },
   {
     "type": "link",
     "label": "Development",
     "href": "/paper/dev",
     "customEmoji": "mdi:code-braces",
+    "description": "Create plugins with the Paper API in order to extend Minecraft with custom and modified behavior.",
   },
   {
     "type": "link",
     "label": "Contributing",
     "href": "/paper/contributing",
     "customEmoji": "mdi:comment-edit",
+    "description": "Contribute code changes to the Paper server.",
   },
 ]}/>
diff --git a/docs/paper/dev/README.mdx b/docs/paper/dev/README.mdx
index 47307b5b1..4a3f549b9 100644
--- a/docs/paper/dev/README.mdx
+++ b/docs/paper/dev/README.mdx
@@ -1,10 +1,9 @@
 import DocCardList from "@theme/DocCardList";
 import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
 
-# Development Guide
+# Paper Development
 
-Welcome to the Paper development guide! This guide includes information and tutorials for developers
-on how to create and expand on Paper plugins.
+Create plugins with the Paper API in order to extend Minecraft with custom and modified behavior.
 
 ---
 
diff --git a/docs/paper/dev/api/README.mdx b/docs/paper/dev/api/README.mdx
deleted file mode 100644
index b5048c957..000000000
--- a/docs/paper/dev/api/README.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
-import DocCardList from "@theme/DocCardList";
-import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
-
-# Paper API
-
-Welcome to the Paper API guide!
-This guide includes information for developers about how to use specific parts of the Paper API.
-
----
-
-<DocCardList items={useCurrentSidebarCategory().items} />
diff --git a/docs/paper/dev/getting-started/README.mdx b/docs/paper/dev/getting-started/README.mdx
deleted file mode 100644
index 1f89bab23..000000000
--- a/docs/paper/dev/getting-started/README.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
-import DocCardList from "@theme/DocCardList";
-import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
-
-# Development Guide
-
-Welcome to the Paper development guide! This guide includes information and tutorials on
-how to start developing plugins for Paper.
-
----
-
-<DocCardList items={useCurrentSidebarCategory().items} />
diff --git a/docs/paper/dev/misc/README.mdx b/docs/paper/dev/misc/README.mdx
deleted file mode 100644
index 5cfd897a8..000000000
--- a/docs/paper/dev/misc/README.mdx
+++ /dev/null
@@ -1,10 +0,0 @@
-import DocCardList from "@theme/DocCardList";
-import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
-
-# Miscellaneous Development Guides
-
-These guides are for helping developers with parts of the development process that don't fit into the other categories.
-
----
-
-<DocCardList items={useCurrentSidebarCategory().items} />
diff --git a/src/css/custom.css b/src/css/custom.css
index 5fc816860..e52aac4b3 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -40,6 +40,35 @@ html[data-theme="dark"] {
   --eol-message-background-color: rgb(92, 15, 18);
 }
 
+.theme-doc-sidebar-item-link > a::before,
+.theme-doc-sidebar-item-category > div > a::before {
+  margin-right: 0.3rem;
+  height: 24px;
+  width: 24px;
+}
+
+.theme-doc-sidebar-item-link > a::before {
+  content: url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iYmxhY2siIGQ9Ik0xNCAySDZhMiAyIDAgMCAwLTIgMnYxNmEyIDIgMCAwIDAgMiAyaDEyYTIgMiAwIDAgMCAyLTJWOHptNCAxOEg2VjRoN3Y1aDV6Ii8+PC9zdmc+);
+}
+
+.theme-doc-sidebar-item-category > div > a::before {
+  content: url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iYmxhY2siIGQ9Ik03IDVoMTR2Mkg3em0wIDh2LTJoMTR2MnpNNCA0LjVBMS41IDEuNSAwIDAgMSA1LjUgNkExLjUgMS41IDAgMCAxIDQgNy41QTEuNSAxLjUgMCAwIDEgMi41IDZBMS41IDEuNSAwIDAgMSA0IDQuNW0wIDZBMS41IDEuNSAwIDAgMSA1LjUgMTJBMS41IDEuNSAwIDAgMSA0IDEzLjVBMS41IDEuNSAwIDAgMSAyLjUgMTJBMS41IDEuNSAwIDAgMSA0IDEwLjVNNyAxOXYtMmgxNHYyem0tMy0yLjVBMS41IDEuNSAwIDAgMSA1LjUgMThBMS41IDEuNSAwIDAgMSA0IDE5LjVBMS41IDEuNSAwIDAgMSAyLjUgMThBMS41IDEuNSAwIDAgMSA0IDE2LjUiLz48L3N2Zz4=);
+}
+
+@media (prefers-color-scheme: dark) {
+  .theme-doc-sidebar-item-link > a::before {
+    content: url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xNCAySDZhMiAyIDAgMCAwLTIgMnYxNmEyIDIgMCAwIDAgMiAyaDEyYTIgMiAwIDAgMCAyLTJWOHptNCAxOEg2VjRoN3Y1aDV6Ii8+PC9zdmc+);
+  }
+
+  .theme-doc-sidebar-item-category > div > a::before {
+    content: url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik03IDVoMTR2Mkg3em0wIDh2LTJoMTR2MnpNNCA0LjVBMS41IDEuNSAwIDAgMSA1LjUgNkExLjUgMS41IDAgMCAxIDQgNy41QTEuNSAxLjUgMCAwIDEgMi41IDZBMS41IDEuNSAwIDAgMSA0IDQuNW0wIDZBMS41IDEuNSAwIDAgMSA1LjUgMTJBMS41IDEuNSAwIDAgMSA0IDEzLjVBMS41IDEuNSAwIDAgMSAyLjUgMTJBMS41IDEuNSAwIDAgMSA0IDEwLjVNNyAxOXYtMmgxNHYyem0tMy0yLjVBMS41IDEuNSAwIDAgMSA1LjUgMThBMS41IDEuNSAwIDAgMSA0IDE5LjVBMS41IDEuNSAwIDAgMSAyLjUgMThBMS41IDEuNSAwIDAgMSA0IDE2LjUiLz48L3N2Zz4=);
+  }
+}
+
+.theme-doc-sidebar-menu > li:first-child > a::before {
+  display: none;
+}
+
 .eol-message {
   width: 100%;
   min-height: 5rem;
@@ -58,6 +87,11 @@ html[data-theme="dark"] {
   margin: 0;
 }
 
+.sidebarTitle {
+  font-size: 0.8rem;
+  font-weight: bold;
+}
+
 .button.button--secondary {
   color: #f6f7f8;
 }
diff --git a/src/theme/DocCard/index.tsx b/src/theme/DocCard/index.tsx
index 2330bca58..4c9b6f6f2 100644
--- a/src/theme/DocCard/index.tsx
+++ b/src/theme/DocCard/index.tsx
@@ -7,19 +7,15 @@ import { translate } from "@docusaurus/Translate";
 
 import type { Props } from "@theme/DocCard";
 import Heading from "@theme/Heading";
-import type { PropSidebarItemCategory, PropSidebarItemLink } from "@docusaurus/plugin-content-docs";
+import type {
+  PropSidebarItemCategory,
+  PropSidebarItemHtml,
+  PropSidebarItemLink,
+} from "@docusaurus/plugin-content-docs";
 
 import styles from "./styles.module.css";
 import { Icon } from "@iconify/react";
 
-function CardContainer({ href, children }: { href: string; children: ReactNode }): JSX.Element {
-  return (
-    <Link href={href} className={clsx("card padding--lg", styles.cardContainer)}>
-      {children}
-    </Link>
-  );
-}
-
 function CardLayout({
   href,
   icon,
@@ -32,16 +28,23 @@ function CardLayout({
   description?: string;
 }): JSX.Element {
   return (
-    <CardContainer href={href}>
-      <Heading as="h2" className={clsx("text--truncate", styles.cardTitle)} title={title}>
-        {icon} {title}
-      </Heading>
-      {description && (
-        <p className={clsx("text--truncate", styles.cardDescription)} title={description}>
-          {description}
-        </p>
-      )}
-    </CardContainer>
+    <Link href={href} className={clsx("padding-horiz--md", styles.cardContainer)}>
+      {icon}
+      <div className={clsx("padding-left--md")}>
+        <Heading
+          as="h2"
+          className={clsx("margin-bottom--sm", styles.linkBlue, styles.cardTitle)}
+          title={title}
+        >
+          {title}
+        </Heading>
+        {description && (
+          <p className={clsx(styles.cardDescription)} title={description}>
+            {description}
+          </p>
+        )}
+      </div>
+    </Link>
   );
 }
 
@@ -56,7 +59,7 @@ function CardCategory({ item }: { item: PropSidebarItemCategory }): JSX.Element
   return (
     <CardLayout
       href={href}
-      icon="🗃️"
+      icon={<Icon className={"margin-right--sm"} icon="mdi:format-list-bulleted" height={25} />}
       title={item.label}
       description={
         item.description ??
@@ -82,9 +85,9 @@ function CardLink({ item }: { item: EmojiPropsSidebarItemLink }): JSX.Element {
   const icon = item.customEmoji ? (
     <Icon className={"margin-right--sm"} icon={item.customEmoji} height={25} />
   ) : isInternalUrl(item.href) ? (
-    "📄️"
+    <Icon className={"margin-right--sm"} icon="mdi:paper-outline" height={25} />
   ) : (
-    "🔗"
+    <Icon className={"margin-right--sm"} icon="mdi:format-list-bulleted" height={25} />
   );
   const doc = useDocById(item.docId ?? undefined);
   return (
@@ -97,12 +100,18 @@ function CardLink({ item }: { item: EmojiPropsSidebarItemLink }): JSX.Element {
   );
 }
 
+function Header({ item }: { item: PropSidebarItemHtml }): JSX.Element {
+  return <h2>{item.value}</h2>;
+}
+
 export default function DocCard({ item }: Props): JSX.Element {
   switch (item.type) {
     case "link":
       return <CardLink item={item} />;
     case "category":
       return <CardCategory item={item} />;
+    case "html":
+      return <Header item={item} />;
     default:
       throw new Error(`unknown item type ${JSON.stringify(item)}`);
   }
diff --git a/src/theme/DocCard/styles.module.css b/src/theme/DocCard/styles.module.css
index d56bc2069..ed66df7a0 100644
--- a/src/theme/DocCard/styles.module.css
+++ b/src/theme/DocCard/styles.module.css
@@ -3,15 +3,9 @@
   --ifm-link-hover-color: var(--ifm-color-emphasis-700);
   --ifm-link-hover-decoration: none;
 
-  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
-  border: 1px solid var(--ifm-color-emphasis-200);
-  transition: all var(--ifm-transition-fast) ease;
-  transition-property: border, box-shadow;
-}
-
-.cardContainer:hover {
-  border-color: var(--ifm-color-primary);
-  box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%);
+  display: flex;
+  flex-direction: row;
+  align-items: center;
 }
 
 .cardContainer *:last-child {
@@ -19,10 +13,14 @@
 }
 
 .cardTitle {
-  font-size: 1.2rem;
+  font-size: 1rem;
   display: flex;
 }
 
 .cardDescription {
-  font-size: 0.8rem;
+  font-size: 1rem;
+}
+
+.linkBlue {
+  color: var(--ifm-color-primary);
 }
diff --git a/src/theme/DocCardList/index.tsx b/src/theme/DocCardList/index.tsx
new file mode 100644
index 000000000..aabdcdf78
--- /dev/null
+++ b/src/theme/DocCardList/index.tsx
@@ -0,0 +1,27 @@
+import React from "react";
+import clsx from "clsx";
+import { useCurrentSidebarCategory, filterDocCardListItems } from "@docusaurus/theme-common";
+import DocCard from "@theme/DocCard";
+import type { Props } from "@theme/DocCardList";
+
+function DocCardListForCurrentSidebarCategory({ className }: Props) {
+  const category = useCurrentSidebarCategory();
+  return <DocCardList items={category.items} className={className} />;
+}
+
+export default function DocCardList(props: Props): JSX.Element {
+  const { items, className } = props;
+  if (!items) {
+    return <DocCardListForCurrentSidebarCategory {...props} />;
+  }
+  const filteredItems = filterDocCardListItems(items);
+  return (
+    <section>
+      {filteredItems.map((item, index) => (
+        <article key={index} className="margin-bottom--lg">
+          <DocCard item={item} />
+        </article>
+      ))}
+    </section>
+  );
+}
diff --git a/vercel.json b/vercel.json
index 27617d45e..70e44e9ba 100644
--- a/vercel.json
+++ b/vercel.json
@@ -35,6 +35,18 @@
     {
       "source": "/paper/configuration",
       "destination": "/paper/reference/configuration"
+    },
+    {
+      "source": "/paper/dev/getting-started",
+      "destination": "/paper/dev"
+    },
+    {
+      "source": "/paper/dev/api",
+      "destination": "/paper/dev"
+    },
+    {
+      "source": "/paper/dev/misc",
+      "destination": "/paper/dev"
     }
   ],
   "headers": [