[TA-5120] Add Separators & labels to sections

docs/changelog/v0.1.x/changelog.md

@@ -1,5 +1,7 @@
 ---
 sidebar_position: 0
+sectionTopLabel: Introduction
+sectionBottomLabel: Versions
 ---
 
 # Changelog

docs/docs/intro.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 1
+sectionTopLabel: Introduction
 ---
 
 # Getting Started

docs/docs/keypairs.md

@@ -1,6 +1,7 @@
 ---
 sidebar_position: 5
 pagination_next: xrpl/currency
+sectionTopLabel: Packages
 ---
 
 # keypairs

docs/docusaurus.config.ts

@@ -1,6 +1,7 @@
 import { themes as prismThemes } from "prism-react-renderer";
 import type { Config } from "@docusaurus/types";
 import type * as Preset from "@docusaurus/preset-classic";
+import { sidebarLabelGenerator } from "./src/theme/sidebar/sidebarLabelGenerator";
 
 // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
 
@@ -39,13 +40,14 @@ const config: Config = {
       "classic",
       {
         docs: {
-          sidebarPath: "./sidebars.ts",
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
+          sidebarPath: require.resolve("./sidebars.ts"),
           editUrl: "https://github.com/Peersyst/xrpl-go/tree/main/docs",
+
+          // Custom sidebar items generator check /src/theme/sidebar/sidebarLabelGenerator.ts
+          sidebarItemsGenerator: sidebarLabelGenerator,
         },
         theme: {
-          customCss: "./src/css/custom.css",
+          customCss: require.resolve("./src/css/custom.css"),
         },
       } satisfies Preset.Options,
     ],
@@ -66,6 +68,9 @@ const config: Config = {
         path: "changelog",
         routeBasePath: "changelog",
         sidebarPath: "./sidebarsChangelog.ts",
+
+        // Custom sidebar items generator check /src/theme/sidebar/sidebarLabelGenerator.ts
+        sidebarItemsGenerator: sidebarLabelGenerator,
       },
     ],
   ],
@@ -90,7 +95,6 @@ const config: Config = {
           label: "Changelog",
           position: "left",
 
-          // Uncomment the following lines to enable dropdown multiple changelog versions
           items: [
             {
               type: "docSidebar",
@@ -139,7 +143,7 @@ const config: Config = {
             },
             {
               label: "Changelog",
-              to: "changelog/v0.1.x/changelog",
+              to: "changelog/v0.1.x/changelog", // When adding a new changelog version, update this path
             },
           ],
         },

docs/src/css/custom.css

@@ -6,42 +6,34 @@
 
 /* You can override the default Infima variables here. */
 :root {
-  --ifm-color-primary: #AC5CFB;
-  --ifm-color-primary-dark: #AC5CFB;
-  --ifm-color-primary-darker: #AC5CFB;
-  --ifm-color-primary-darkest: #AC5CFB;
-  --ifm-color-primary-light: #AC5CFB;
-  --ifm-color-primary-lighter: #AC5CFB;
-  --ifm-color-primary-lightest: #AC5CFB;
+  --ifm-color-primary: #ac5cfb;
+  --ifm-color-primary-dark: #ac5cfb;
+  --ifm-color-primary-darker: #ac5cfb;
+  --ifm-color-primary-darkest: #ac5cfb;
+  --ifm-color-primary-light: #ac5cfb;
+  --ifm-color-primary-lighter: #ac5cfb;
+  --ifm-color-primary-lightest: #ac5cfb;
   --ifm-code-font-size: 95%;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
 }
 
 /* For readability concerns, you should choose a lighter palette in dark mode. */
-[data-theme='dark'] {
-  --ifm-color-primary: #AC5CFB;
-  --ifm-color-primary-dark: #AC5CFB;
-  --ifm-color-primary-darker: #AC5CFB;
-  --ifm-color-primary-darkest: #AC5CFB;
-  --ifm-color-primary-light: #AC5CFB;
-  --ifm-color-primary-lighter: #AC5CFB;
-  --ifm-color-primary-lightest: #AC5CFB;
+[data-theme="dark"] {
+  --ifm-color-primary: #ac5cfb;
+  --ifm-color-primary-dark: #ac5cfb;
+  --ifm-color-primary-darker: #ac5cfb;
+  --ifm-color-primary-darkest: #ac5cfb;
+  --ifm-color-primary-light: #ac5cfb;
+  --ifm-color-primary-lighter: #ac5cfb;
+  --ifm-color-primary-lightest: #ac5cfb;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }
 
 main {
-  background-image: 
-    url('/img/bg-top.png'),
-    url('/img/bg-bottom.png');
-  background-position: 
-    top left, 
-    bottom right;
-  background-repeat: 
-    no-repeat, 
-    no-repeat;
-  background-size: 
-    200px, 
-    200px;
+  background-image: url("/img/bg-top.png"), url("/img/bg-bottom.png");
+  background-position: top left, bottom right;
+  background-repeat: no-repeat, no-repeat;
+  background-size: 200px, 200px;
 }
 
 .footer {
@@ -82,3 +74,17 @@ main {
   line-height: 1.6;
   margin-bottom: 2rem;
 }
+
+/* src/theme/sidebar/sidebar.module.css */
+.sidebarSectionLabel {
+  /* no margins */
+  margin: 0;
+  /* make it bigger */
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  /* your color */
+  color: rgb(85, 86, 87);
+  line-height: 1.5;
+  /* pull it left of links */
+  margin-left: -0.5rem;
+}

docs/src/theme/sidebar/sidebarLabelGenerator.ts

@@ -0,0 +1,58 @@
+/**
+ * Custom sidebar items generator that injects “top” and “bottom” section labels
+ * around individual docs based on front-matter flags.
+ *
+ * To use, add these to the **YAML front-matter** of your Markdown file (no quotes needed):
+ *
+ * ```md
+ * ---
+ * title: Changelog
+ * sectionTopLabel: Introduction     # injects “Introduction” above this doc
+ * sectionBottomLabel: Versions      # injects “Versions” below this doc
+ * ---
+ * ```
+ *
+ * @param args
+ *   - defaultSidebarItemsGenerator: function to produce the normal sidebar items
+ *   - docs: array of all doc metadata (including your frontMatter)
+ * @returns
+ *   A new array of sidebar items, with `<div class="sidebar-section-label">…</div>`
+ *   injected before/after any doc that defines `sectionTopLabel` or
+ *   `sectionBottomLabel` in its front-matter.
+ */
+export async function sidebarLabelGenerator(args) {
+  const defaultItems = await args.defaultSidebarItemsGenerator!(args);
+  return defaultItems.flatMap((item) => {
+    // only modify real docs (skip categories, html, etc.)
+    if (item.type === "doc") {
+      const docMeta = args.docs.find((d) => d.id === item.id);
+      const { sectionTopLabel, sectionBottomLabel } =
+        docMeta?.frontMatter || {};
+      const out = [];
+
+      // If the front-matter had a sectionTopLabel, inject it above
+      if (sectionTopLabel) {
+        out.push({
+          type: "html",
+          value: `<div class="sidebarSectionLabel">${sectionTopLabel}</div>`,
+          defaultStyle: true,
+        });
+      }
+
+      out.push(item);
+
+      // If the front-matter had a sectionBottomLabel, inject it below
+      if (sectionBottomLabel) {
+        out.push({
+          type: "html",
+          value: `<div class="sidebarSectionLabel">${sectionBottomLabel}</div>`,
+          defaultStyle: true,
+        });
+      }
+
+      return out;
+    }
+
+    return [item];
+  });
+}