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.

Author: sowelipililimute

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,87 +83,77 @@ 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",
         id: "dev/README",
       },
       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",

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.",
   },
 ]}/>

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.
 
 ---
 

docs/paper/dev/api/README.mdx

@@ -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;
 }

docs/paper/dev/getting-started/README.mdx

@@ -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,13 @@ function CardCategory({ item }: { item: PropSidebarItemCategory }): JSX.Element
   return (
     <CardLayout
       href={href}
-      icon="🗃️"
+      icon={
+        <Icon
+          className={clsx("margin-right--sm", styles.cardIcon)}
+          icon="mdi:format-list-bulleted"
+          width={24}
+        />
+      }
       title={item.label}
       description={
         item.description ??
@@ -80,11 +89,23 @@ type EmojiPropsSidebarItemLink = PropSidebarItemLink & {
 
 function CardLink({ item }: { item: EmojiPropsSidebarItemLink }): JSX.Element {
   const icon = item.customEmoji ? (
-    <Icon className={"margin-right--sm"} icon={item.customEmoji} height={25} />
+    <Icon
+      className={clsx("margin-right--sm", styles.cardIcon)}
+      icon={item.customEmoji}
+      width={24}
+    />
   ) : isInternalUrl(item.href) ? (
-    "📄️"
+    <Icon
+      className={clsx("margin-right--sm", styles.cardIcon)}
+      icon="mdi:paper-outline"
+      width={24}
+    />
   ) : (
-    "🔗"
+    <Icon
+      className={clsx("margin-right--sm", styles.cardIcon)}
+      icon="mdi:format-list-bulleted"
+      width={24}
+    />
   );
   const doc = useDocById(item.docId ?? undefined);
   return (
@@ -97,12 +118,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)}`);
   }