From 468fcb3992f29b83bbb62c4da642f51f42b68819 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Fri, 5 Dec 2025 19:06:44 +0000
Subject: [PATCH] Group endpoints by module

Makes the list of endpoints easier to scan.
---
 assets/scss/_styles_project.scss     | 12 ++++++++-
 data/cs_modules.yaml                 | 39 ++++++++++++++++++++++++++++
 layouts/_partials/endpoints-toc.html | 22 +++++++++++++---
 layouts/_shortcodes/cs-module.html   | 28 ++++++++++++++++++++
 4 files changed, 97 insertions(+), 4 deletions(-)
 create mode 100644 data/cs_modules.yaml

diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss
index 2e1d2da9..c0a9c457 100644
--- a/assets/scss/_styles_project.scss
+++ b/assets/scss/_styles_project.scss
@@ -281,7 +281,6 @@ Custom SCSS for the Matrix spec
   }
 
   .endpoint-list .http-api-method {
-    font-weight: $font-weight-bold;
     margin-right: 0.35rem;
   }
 
@@ -295,6 +294,17 @@ Custom SCSS for the Matrix spec
     font-weight: $font-weight-bold;
     margin-left: 0.35rem;
   }
+
+  .endpoint-module {
+    &:not(:first-child) {
+      margin-top: 0.75rem;
+    }
+  }
+
+  .endpoint-module-title {
+    font-weight: $font-weight-bold;
+    margin-bottom: 0.35rem;
+  }
 }
 
 .page-description {
diff --git a/data/cs_modules.yaml b/data/cs_modules.yaml
new file mode 100644
index 00000000..d6df20aa
--- /dev/null
+++ b/data/cs_modules.yaml
@@ -0,0 +1,39 @@
+account_data: "Client Config"
+admin: "Server Administration"
+content_repo: "Content repository"
+device_management: "Device Management"
+dm: "Direct Messaging"
+end_to_end_encryption: "End-to-End Encryption"
+event_annotations: "Event annotations and reactions"
+event_context: "Event Context"
+event_replacements: "Event replacements"
+guest_access: "Guest Access"
+history_visibility: "Room History Visibility"
+ignore_users: "Ignoring Users"
+instant_messaging: "Instant Messaging"
+mentions: "User and room mentions"
+moderation_policies: "Moderation policy lists"
+openid: "OpenID"
+presence: "Presence"
+push: "Push Notifications"
+read_markers: "Read and unread markers"
+receipts: "Receipts"
+reference_relations: "Reference relations"
+report_content: "Reporting Content"
+rich_replies: "Rich replies"
+room_previews: "Room Previews"
+room_upgrades: "Room Upgrades"
+search: "Server Side Search"
+secrets: "Secrets"
+send_to_device: "Send-to-Device messaging"
+server_acls: "Server Access Control Lists (ACLs) for rooms"
+server_notices: "Server Notices"
+spaces: "Spaces"
+sso_login: "SSO client login/authentication"
+stickers: "Sticker Messages"
+tags: "Room Tagging"
+third_party_invites: "Third-party invites"
+third_party_networks: "Third-party Networks"
+threading: "Threading"
+typing_notifications: "Typing Notifications"
+voip_events: "Voice over IP"
diff --git a/layouts/_partials/endpoints-toc.html b/layouts/_partials/endpoints-toc.html
index f2ccae3b..88d37a09 100644
--- a/layouts/_partials/endpoints-toc.html
+++ b/layouts/_partials/endpoints-toc.html
@@ -13,8 +13,23 @@
   <div class="endpoints-toc mb-4">
     <details>
       <summary>List of Endpoints</summary>
-      <ul class="endpoint-list">
-        {{ range $endpoints }}
+      {{/* Sort by module to group visually */}}
+      {{ $sorted := sort $endpoints "module" }}
+      {{ $current := "" }}
+      {{ $seen := newScratch }}
+      {{ range $sorted }}
+        {{ $mod := .module }}
+        {{ if not $mod }}{{ $mod = "Required" }}{{ end }}
+        {{ if ne $mod $current }}
+          {{ if $current }}</ul></div>{{ end }}
+          <div class="endpoint-module">
+            <div class="endpoint-module-title">{{ $mod }}</div>
+            <ul class="endpoint-list">
+          {{ $current = $mod }}
+        {{ end }}
+        {{ $key := printf "%s|%s" .method .anchor }}
+        {{ if not ($seen.Get $key) }}
+          {{ $seen.Set $key true }}
           <li>
             <a href="#{{ .anchor }}">
               <span class="http-api-method">{{ .method }}</span>
@@ -23,7 +38,8 @@
             </a>
           </li>
         {{ end }}
-      </ul>
+      {{ end }}
+      {{ if $current }}</ul></div>{{ end }}
     </details>
   </div>
 {{ end }}
diff --git a/layouts/_shortcodes/cs-module.html b/layouts/_shortcodes/cs-module.html
index 52c9a5d9..090c6558 100644
--- a/layouts/_shortcodes/cs-module.html
+++ b/layouts/_shortcodes/cs-module.html
@@ -11,6 +11,34 @@
 
 {{ with .Site.GetPage "client-server-api/modules" }}
     {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }}
+        {{/* Preserve previous scratch values so nested modules don't leak */}}
+        {{ $prevPage := .Scratch.Get "endpoint_page" }}
+        {{ $prevModule := .Scratch.Get "endpoint_module" }}
+
+        {{/* Allow endpoints rendered in the module to accumulate on the parent page */}}
+        {{ .Scratch.Set "endpoint_page" $.Page }}
+        {{/* Name the module for grouping in the endpoints list */}}
+        {{ $display := $.Get "title" }}
+        {{ if not $display }}
+          {{ $display = index $.Site.Data.cs_modules $name }}
+        {{ end }}
+        {{ if not $display }}
+          {{ $display = $name }}
+        {{ end }}
+        {{ .Scratch.Set "endpoint_module" $display }}
+
 {{ .RenderShortcodes }}
+
+        {{/* Restore previous scratch values */}}
+        {{ if $prevPage }}
+          {{ .Scratch.Set "endpoint_page" $prevPage }}
+        {{ else }}
+          {{ .Scratch.Delete "endpoint_page" }}
+        {{ end }}
+        {{ if $prevModule }}
+          {{ .Scratch.Set "endpoint_module" $prevModule }}
+        {{ else }}
+          {{ .Scratch.Delete "endpoint_module" }}
+        {{ end }}
     {{ end }}
 {{ end }}