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.
PaperMC · Apr 21, 2024 · fc96bfc · fc96bfc
1 parent 825ccb1
commit fc96bfc
Show file tree

Hide file tree

Showing 9 changed files with 142 additions and 124 deletions.
diff --git a/config/sidebar.paper.ts b/config/sidebar.paper.ts
@@ -89,75 +89,62 @@ 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",
       ],
     },
     {

diff --git 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
diff --git a/docs/paper/dev/getting-started/README.mdx b/docs/paper/dev/getting-started/README.mdx
diff --git a/docs/paper/dev/misc/README.mdx b/docs/paper/dev/misc/README.mdx
diff --git a/src/css/custom.css b/src/css/custom.css
@@ -40,6 +40,31 @@ 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=);
+  }
+}
+
 .eol-message {
   width: 100%;
   min-height: 5rem;
@@ -58,6 +83,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
@@ -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
@@ -3,26 +3,24 @@
   --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 {
   margin-bottom: 0;
 }
 
 .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
@@ -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>
+  );
+}