Inline the module name map

To make it easier to keep it in sync in future.

content/client-server-api/_index.md

@@ -3953,42 +3953,42 @@ operations and run in a resource constrained environment. Like embedded
 applications, they are not intended to be fully-fledged communication
 systems.
 
-{{% cs-module name="instant_messaging" %}}
-{{% cs-module name="rich_replies" %}}
-{{% cs-module name="voip_events" %}}
-{{% cs-module name="typing_notifications" %}}
-{{% cs-module name="receipts" %}}
-{{% cs-module name="read_markers" %}}
-{{% cs-module name="presence" %}}
-{{% cs-module name="content_repo" %}}
-{{% cs-module name="send_to_device" %}}
-{{% cs-module name="device_management" %}}
-{{% cs-module name="end_to_end_encryption" %}}
-{{% cs-module name="secrets" %}}
-{{% cs-module name="history_visibility" %}}
-{{% cs-module name="push" %}}
-{{% cs-module name="third_party_invites" %}}
-{{% cs-module name="search" %}}
-{{% cs-module name="guest_access" %}}
-{{% cs-module name="room_previews" %}}
-{{% cs-module name="tags" %}}
-{{% cs-module name="account_data" %}}
-{{% cs-module name="admin" %}}
-{{% cs-module name="event_context" %}}
-{{% cs-module name="sso_login" %}}
-{{% cs-module name="dm" %}}
-{{% cs-module name="ignore_users" %}}
-{{% cs-module name="stickers" %}}
-{{% cs-module name="report_content" %}}
-{{% cs-module name="third_party_networks" %}}
-{{% cs-module name="openid" %}}
-{{% cs-module name="server_acls" %}}
-{{% cs-module name="mentions" %}}
-{{% cs-module name="room_upgrades" %}}
-{{% cs-module name="server_notices" %}}
-{{% cs-module name="moderation_policies" %}}
-{{% cs-module name="spaces" %}}
-{{% cs-module name="event_replacements" %}}
-{{% cs-module name="event_annotations" %}}
-{{% cs-module name="threading" %}}
-{{% cs-module name="reference_relations" %}}
+{{% cs-module name="Instant Messaging" filename="instant_messaging" %}}
+{{% cs-module name="Rich replies" filename="rich_replies" %}}
+{{% cs-module name="Voice over IP" filename="voip_events" %}}
+{{% cs-module name="Typing Notifications" filename="typing_notifications" %}}
+{{% cs-module name="Receipts" filename="receipts" %}}
+{{% cs-module name="Read and unread markers" filename="read_markers" %}}
+{{% cs-module name="Presence" filename="presence" %}}
+{{% cs-module name="Content repository" filename="content_repo" %}}
+{{% cs-module name="Send-to-Device messaging" filename="send_to_device" %}}
+{{% cs-module name="Device Management" filename="device_management" %}}
+{{% cs-module name="End-to-End Encryption" filename="end_to_end_encryption" %}}
+{{% cs-module name="Secrets" filename="secrets" %}}
+{{% cs-module name="Room History Visibility" filename="history_visibility" %}}
+{{% cs-module name="Push Notifications" filename="push" %}}
+{{% cs-module name="Third-party invites" filename="third_party_invites" %}}
+{{% cs-module name="Server Side Search" filename="search" %}}
+{{% cs-module name="Guest Access" filename="guest_access" %}}
+{{% cs-module name="Room Previews" filename="room_previews" %}}
+{{% cs-module name="Room Tagging" filename="tags" %}}
+{{% cs-module name="Client Config" filename="account_data" %}}
+{{% cs-module name="Server Administration" filename="admin" %}}
+{{% cs-module name="Event Context" filename="event_context" %}}
+{{% cs-module name="SSO client login/authentication" filename="sso_login" %}}
+{{% cs-module name="Direct Messaging" filename="dm" %}}
+{{% cs-module name="Ignoring Users" filename="ignore_users" %}}
+{{% cs-module name="Sticker Messages" filename="stickers" %}}
+{{% cs-module name="Reporting Content" filename="report_content" %}}
+{{% cs-module name="Third-party Networks" filename="third_party_networks" %}}
+{{% cs-module name="OpenID" filename="openid" %}}
+{{% cs-module name="Server Access Control Lists (ACLs) for rooms" filename="server_acls" %}}
+{{% cs-module name="User and room mentions" filename="mentions" %}}
+{{% cs-module name="Room Upgrades" filename="room_upgrades" %}}
+{{% cs-module name="Server Notices" filename="server_notices" %}}
+{{% cs-module name="Moderation policy lists" filename="moderation_policies" %}}
+{{% cs-module name="Spaces" filename="spaces" %}}
+{{% cs-module name="Event replacements" filename="event_replacements" %}}
+{{% cs-module name="Event annotations and reactions" filename="event_annotations" %}}
+{{% cs-module name="Threading" filename="threading" %}}
+{{% cs-module name="Reference relations" filename="reference_relations" %}}

data/cs_modules.yaml

@@ -1,39 +0,0 @@
-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

@@ -1,4 +1,23 @@
-{{/* Minimal list of API endpoints for the current page. */}}
+{{/*
+  
+  Renders a list of API endpoints for the current page, given:
+
+  The outer page's Scratch must contain an "api_endpoints" key, which is either
+  a slice of maps (a list of endpoint metadata dicts) or a map of module name ->
+  slice of endpoint metadata dicts (representing the API modules and the
+  endpoints they each contain). Each slice item must contain the Each endpoint
+  dict must contain the following keys:
+
+    * `anchor`: the HTML anchor for the endpoint
+    * `method`: the HTTP method
+    * `endpoint`: the endpoint path
+    * `summary`: a short summary of the endpoint
+    * `deprecated`: whether the endpoint is deprecated
+    * `module`: the CS API module name, if any, for grouping purposes. If empty,
+      the endpoint is considered "base" or "required".
+  
+*/}}
+
 {{ $raw := .Scratch.Get "api_endpoints" }}
 {{/* Normalize to a slice */}}
 {{ $endpoints := slice }}

layouts/_partials/openapi/render-api.html

@@ -7,6 +7,8 @@
   of each value in `paths` to get a complete URL.
   * `anchor_base`: an optional prefix for the HTML IDs generated by
   this template.
+  * `page`: the (Hugo) Page object to store endpoint metadata in the Scratch of. Used to build the endpoints TOC.
+  * `module`: the current CS API module name, if any. Used to group endpoints in the TOC.
 
   This template replaces the old {{*_http_api}} template.
 

layouts/_partials/openapi/render-operation.html

@@ -7,6 +7,8 @@
   * `operation_data`: the OpenAPI data for the operation
   * `anchor_base`: an optional prefix for the HTML IDs generated by
   this template.
+  * `page`: the (Hugo) Page object to store endpoint metadata in the Scratch of. Used to build the endpoints TOC.
+  * `module`: the current CS API module name, if any. Used to group endpoints in the TOC.
 
   This template renders the operation as a `<section>` containing:
 

layouts/_partials/spec-content.html

@@ -3,9 +3,12 @@
   <h1>{{ .Title }}</h1>
   {{ with .Params.description }}<p class="page-description">{{ . | markdownify }}</p>{{ end }}
 
+  {{/*
+    Render an endpoints table of contents. This is the main difference
+    between our templates (which call the spec-content partial) and the default
+    Docsy template.
+  */}}
   {{ partial "endpoints-toc.html" . }}
 
   {{ .Content }}
-
-  {{ partial "page-meta-lastmod.html" . }}
-</div>
+</div>

layouts/_shortcodes/cs-module.html

@@ -3,14 +3,18 @@
     This template is used to render a Client-Server API Module. Modules are defined
     alongside the `_index.md` for the CS API.
 
-    The `name` parameter is the file name without extension.
+    The following parameters are expected:
+
+    * `filename` the name of the module file to render, without extension (i.e. `spaces`).
+    * `name` the display name of the module (i.e. `Spaces`).
 
 */}}
 
 {{ $name := .Params.name }}
+{{ $filename := .Params.filename }}
 
 {{ with .Site.GetPage "client-server-api/modules" }}
-    {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }}
+    {{ with .Resources.GetMatch (printf "%s%s" $filename ".md") }}
         {{/* Preserve previous scratch values so nested modules don't leak */}}
         {{ $prevPage := .Scratch.Get "endpoint_page" }}
         {{ $prevModule := .Scratch.Get "endpoint_module" }}
@@ -18,14 +22,7 @@
         {{/* 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 }}
+        {{ .Scratch.Set "endpoint_module" $name }}
 
 {{ .RenderShortcodes }}
 

layouts/_shortcodes/http-api.html

@@ -23,11 +23,18 @@
 {{ $api := .Params.api}}
 {{ $anchor_base := .Params.anchor_base}}
 
-{{/* Allow an outer page to collect endpoints (used for modules). */}}
+{{/*
+  
+  Figure out which Page object to pass to the `openapi/render-api` partial.
+  Either our own, or one stored under `endpoint_page` in the Scratch, if one
+  exists.
+
+*/}}
 {{ $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 }}

layouts/content.html

@@ -1,3 +0,0 @@
-{{ define "main" }}
-  {{ partial "spec-content.html" . }}
-{{ end }}

layouts/docs/list.html

@@ -1,14 +1,19 @@
 {{/*
 
-  A simplified version of the list.html partial in Docsy.
+  Override the `layouts/docs/list.html` template from Docsy. While this template
+  is equivalent to `single.html`, it's necessary to override both templates to
+  avoid falling back to the default Docsy templates.
+
+  https://gohugo.io/templates/types/#list
+
+  We use this list template to render the Client-Server API spec page and each
+  of its modules.
+
+  The contents of the "main" block below are inserted into the `./baseof.html`
+  base template.
 
 */}}
 
 {{ define "main" }}
-<div class="td-content">
-	<h1>{{ .Title }}</h1>
-        {{ with .Params.description }}<p class="page-description">{{ . | markdownify }}</p>{{ end }}
-        {{ partial "endpoints-toc.html" . }}
-	{{ .Content }}
-</div>
+  {{ partial "spec-content.html" . }}
 {{ end }}

layouts/docs/single.html

@@ -1,3 +1,19 @@
+{{/*
+
+  Override the `layouts/docs/single.html` template from Docsy. While this template
+  is equivalent to `list.html`, it's necessary to override both templates to
+  avoid falling back to the default Docsy templates.
+
+  https://gohugo.io/templates/types/#single
+
+  We use this single template to render the all API spec pages *except* the
+  Client-Server API. The Client-Server API spec page contains modules, and thus
+  is handled separately, via the `layouts/docs/list.html` template.
+
+  The contents of the "main" block below are inserted into the `./baseof.html`
+  base template.
+
+*/}}
 {{ define "main" }}
   {{ partial "spec-content.html" . }}
 {{ end }}