Improve styling of the endpoints list

- Add a hover effect over endpoints
- Make the method bold to differentiate it from the endpoint itself
- Make cs module titles larger

assets/scss/_styles_project.scss

@@ -278,11 +278,17 @@ Custom SCSS for the Matrix spec
   .endpoint-list a {
     text-decoration: none;
     color: inherit;
+    padding: 0.05rem 0.25rem;
+    border-radius: 0.2rem;
+
+    &:hover {
+      background-color: $secondary-background;
+    }
   }
 
   .endpoint-list .http-api-method {
-    font-weight: $font-weight-bold;
     margin-right: 0.35rem;
+    font-weight: $font-weight-bold;
   }
 
   .endpoint-path {
@@ -295,6 +301,18 @@ 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;
+    font-size: 1.20rem;
+    margin-bottom: 0.35rem;
+  }
 }
 
 .page-description {

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"

layouts/_partials/endpoints-toc.html

@@ -13,17 +13,30 @@
   <div class="endpoints-toc mb-4">
     <details>
       <summary>List of Endpoints</summary>
-      <ul class="endpoint-list">
+      {{/* Sort by module to group visually */}}
-        {{ range $endpoints }}
+      {{ $sorted := sort $endpoints "module" }}
-          <li>
+      {{ $current := "" }}
-            <a href="#{{ .anchor }}">
+      {{ range $sorted }}
-              <span class="http-api-method">{{ .method }}</span>
+        {{ $mod := .module }}
-              <span class="endpoint-path">{{ .endpoint }}</span>
+        {{/* Set a title for the base endpoints */}}
-              {{ if .deprecated }}<span class="endpoint-deprecated">(deprecated)</span>{{ end }}
+        {{ if not $mod }}{{ $mod = "Required" }}{{ end }}
-            </a>
+        {{ if ne $mod $current }}
-          </li>
+          {{ if $current }}</ul></div>{{ end }}
+          <div class="endpoint-module">
+            <div class="endpoint-module-title">{{ $mod }}</div>
+            <ul class="endpoint-list">
+          {{ $current = $mod }}
         {{ end }}
-      </ul>
+        {{ $key := printf "%s|%s" .method .anchor }}
+        <li>
+          <a href="#{{ .anchor }}">
+            <span class="http-api-method">{{ .method }}</span>
+            <span class="endpoint-path">{{ .endpoint }}</span>
+            {{ if .deprecated }}<span class="endpoint-deprecated">(deprecated)</span>{{ end }}
+          </a>
+        </li>
+      {{ end }}
+      {{ if $current }}</ul></div>{{ end }}
     </details>
   </div>
 {{ end }}

layouts/_partials/openapi/render-api.html

@@ -16,6 +16,7 @@
 {{ $base_url := .base_url }}
 {{ $anchor_base := .anchor_base }}
 {{ $page := .page }}
+{{ $module := .module }}
 
 {{ range $path_name, $path_data := $api_data.paths }}
 
@@ -27,28 +28,28 @@
 
     {{ with $path_data.get }}
 
-        {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base "page" $page) }}
+        {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }}
         {{ partial "openapi/render-operation" $operation_params }}
 
     {{ end }}
 
     {{ with $path_data.post }}
 
-        {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base "page" $page) }}
+        {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }}
         {{ partial "openapi/render-operation" $operation_params }}
 
     {{ end }}
 
     {{ with $path_data.put }}
 
-        {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base "page" $page) }}
+        {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }}
         {{ partial "openapi/render-operation" $operation_params }}
 
     {{ end }}
 
     {{ with $path_data.delete }}
 
-        {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base "page" $page) }}
+        {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }}
         {{ partial "openapi/render-operation" $operation_params }}
 
     {{ end }}

layouts/_partials/openapi/render-operation.html

@@ -23,6 +23,7 @@
 {{ $endpoint := .endpoint }}
 {{ $operation_data := .operation_data }}
 {{ $page := .page }}
+{{ $module := .module }}
 
 {{ $anchor := "" }}
 {{ if .anchor_base }}
@@ -33,11 +34,22 @@
 {{/* Collect endpoints for the on-page endpoints TOC */}}
 {{ if $page }}
   {{/* Store each endpoint's metadata in a scratch variable */}}
-  {{ $entry := dict "anchor" $anchor "method" $method "endpoint" $endpoint "summary" $operation_data.summary "deprecated" $operation_data.deprecated }}
+  {{ $entry := dict "anchor" $anchor "method" $method "endpoint" $endpoint "summary" $operation_data.summary "deprecated" $operation_data.deprecated "module" $module }}
+  {{ if not ($page.Scratch.Get "api_endpoints_seen") }}
+    {{ $page.Scratch.Set "api_endpoints_seen" dict }}
+  {{ end }}
+  {{/* Keep a map of seen endpoints. This is necessary as this partial may be
+       rendered multiple times for the same endpoint (e.g. in the TOC and
+       in the main content), leading to duplicates. */}}
+  {{ $seen := $page.Scratch.Get "api_endpoints_seen" }}
+  {{ $key := printf "%s|%s" $method $endpoint }}
+  {{ if not (index $seen $key) }}
   {{ if not (reflect.IsSlice ($page.Scratch.Get "api_endpoints")) }}
     {{ $page.Scratch.Set "api_endpoints" (slice) }}
   {{ end }}
   {{ $page.Scratch.Add "api_endpoints" (slice $entry) }}
+    {{ $page.Scratch.SetInMap "api_endpoints_seen" $key true }}
+  {{ end }}
 {{ end }}
 
 <section class="rendered-data">

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

layouts/_shortcodes/http-api.html

@@ -23,6 +23,13 @@
 {{ $api := .Params.api}}
 {{ $anchor_base := .Params.anchor_base}}
 
+{{/* Allow an outer page to collect endpoints (used for modules). */}}
+{{ $target_page := .Page }}
+{{ with .Page.Scratch.Get "endpoint_page" }}
+  {{ $target_page = . }}
+{{ end }}
+{{ $module_name := .Page.Scratch.Get "endpoint_module" }}
+
 {{ $api_data := index .Site.Data.api .Params.spec .Params.api }}
 {{ $base_url := (index $api_data.servers 0).variables.basePath.default }}
 {{ $path := delimit (slice "api" $spec $api) "/" }}
@@ -30,4 +37,4 @@
 {{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }}
 {{ $api_data = partial "json-schema/resolve-allof" $api_data }}
 
-{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base "page" .Page) }}
+{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base "page" $target_page "module" $module_name) }}