Merge 42a1bc370f into 13aa6e83ae

This just looks visually nicer. You have an introduction paragraph, then
the list of endpoints, then the spec.

assets/scss/_styles_project.scss

@@ -257,6 +257,51 @@ Custom SCSS for the Matrix spec
 
 }
 
+.endpoints-toc {
+  summary {
+    cursor: pointer;
+    font-weight: $font-weight-bold;
+    font-size: 1.05rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .endpoint-list {
+    list-style: none;
+    padding-left: 0;
+    margin: 0;
+  }
+
+  .endpoint-list li {
+    margin: 0.2rem 0;
+  }
+
+  .endpoint-list a {
+    text-decoration: none;
+    color: inherit;
+  }
+
+  .endpoint-list .http-api-method {
+    font-weight: $font-weight-bold;
+    margin-right: 0.35rem;
+  }
+
+  .endpoint-path {
+    font-family: $font-family-monospace;
+    color: $secondary;
+  }
+
+  .endpoint-deprecated {
+    color: $danger;
+    font-weight: $font-weight-bold;
+    margin-left: 0.35rem;
+  }
+}
+
+.page-description {
+  margin-bottom: 1rem;
+  color: inherit;
+}
+
 /* Styles for alert boxes */
 .alert {
   &.note {

changelogs/internal/newsfragments/2262.clarification

@@ -0,0 +1 @@
+Add a list of endpoints to the top of each spec page.

content/application-service-api.md

@@ -2,16 +2,14 @@
 title: "Application Service API"
 weight: 30
 type: docs
+description: |
+  The Matrix client-server API and server-server APIs provide a consistent,
+  self-contained federated messaging fabric but leave little room for custom
+  server-side behaviour such as gateways, filters, or extensible hooks. The
+  Application Service API defines a standard way to add this extensible
+  functionality, independent of the underlying homeserver implementation.
 ---
 
-The Matrix client-server API and server-server APIs provide the means to
-implement a consistent self-contained federated messaging fabric.
-However, they provide limited means of implementing custom server-side
-behaviour in Matrix (e.g. gateways, filters, extensible hooks etc). The
-Application Service API (AS API) defines a standard API to allow such
-extensible functionality to be implemented irrespective of the
-underlying homeserver implementation.
-
 ## Application Services
 
 Application services are passive and can only observe events from the

content/client-server-api/_index.md

@@ -2,14 +2,14 @@
 title: "Client-Server API"
 weight: 10
 type: docs
+description: |
+  The client-server API allows clients to send messages, control rooms and
+  synchronise conversation history. It is designed to support both lightweight
+  clients which store no state and lazy-load data from the server as required,
+  as well as heavyweight clients which maintain a full local persistent copy of
+  server state.
 ---
 
-The client-server API allows clients to
-send messages, control rooms and synchronise conversation history. It is
-designed to support both lightweight clients which store no state and
-lazy-load data from the server as required - as well as heavyweight
-clients which maintain a full local persistent copy of server state.
-
 ## API Standards
 
 {{% boxes/note %}}

content/identity-service-api.md

@@ -2,16 +2,14 @@
 title: "Identity Service API"
 weight: 40
 type: docs
----
+description: |
-
   The Matrix client-server and server-server APIs are largely expressed in
-Matrix user identifiers. From time to time, it is useful to refer to
+  Matrix user identifiers. Sometimes it is useful to refer to users by other
-users by other ("third-party") identifiers, or "3PID"s, e.g. their email
+  (“third-party”) identifiers such as email addresses or phone numbers. The
-address or phone number. This Identity Service Specification describes
+  Identity Service API describes how mappings between 3PIDs and Matrix user
-how mappings between third-party identifiers and Matrix user identifiers
+  IDs can be established, validated, and used; in practice this has been
-can be established, validated, and used. This description technically
+  applied to email addresses and phone numbers.
-may apply to any 3PID, but in practice has only been applied
+---
-specifically to email addresses and phone numbers.
 
 ## General principles
 

content/push-gateway-api.md

@@ -2,12 +2,11 @@
 title: "Push Gateway API"
 weight: 50
 type: docs
+description: |
+  Clients may want to receive push notifications when events are received at the
+  homeserver. This is managed by a distinct entity called the Push Gateway.
 ---
 
-Clients may want to receive push notifications when events are received
-at the homeserver. This is managed by a distinct entity called the Push
-Gateway.
-
 ## Overview
 
 A client's homeserver forwards information about received events to the

content/server-server-api.md

@@ -2,18 +2,13 @@
 title: "Server-Server API"
 weight: 20
 type: docs
----
+description: |
-
+  Matrix homeservers use the Federation APIs (also known as server-server APIs)
-Matrix homeservers use the Federation APIs (also known as server-server
+  to communicate with each other. Homeservers use these APIs to push messages in
-APIs) to communicate with each other. Homeservers use these APIs to push
+  real-time, retrieve historic messages, and query profile or presence
-messages to each other in real-time, to retrieve historic messages from
+  information about users on other servers. The APIs are implemented over HTTPS,
-each other, and to query profile and presence information about users on
+  with authentication provided by public key signatures both at the TLS
-each other's servers.
+  transport layer and in HTTP Authorization headers.
-
-The APIs are implemented using HTTPS requests between each of the
-servers. These HTTPS requests are strongly authenticated using public
-key signatures at the TLS transport layer and using public key
-signatures in HTTP Authorization headers at the HTTP layer.
 
   There are three main kinds of communication that occur between
   homeservers:
@@ -45,6 +40,8 @@ EDUs and PDUs are further wrapped in an envelope called a Transaction,
   which is transferred from the origin to the destination homeserver using
   an HTTPS PUT request.
 
+---
+
 ## API standards
 
 The mandatory baseline for server-server communication in Matrix is

layouts/_partials/endpoints-toc.html

@@ -0,0 +1,29 @@
+{{/* Minimal list of API endpoints for the current page. */}}
+{{ $raw := .Scratch.Get "api_endpoints" }}
+{{/* Normalize to a slice */}}
+{{ $endpoints := slice }}
+{{ if reflect.IsSlice $raw }}
+  {{ $endpoints = $raw }}
+{{ else if reflect.IsMap $raw }}
+  {{ range $raw }}
+    {{ $endpoints = append $endpoints . }}
+  {{ end }}
+{{ end }}
+{{ if gt (len $endpoints) 0 }}
+  <div class="endpoints-toc mb-4">
+    <details>
+      <summary>List of Endpoints</summary>
+      <ul class="endpoint-list">
+        {{ range $endpoints }}
+          <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 }}
+      </ul>
+    </details>
+  </div>
+{{ end }}

layouts/_partials/openapi/render-api.html

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

layouts/_partials/openapi/render-operation.html

@@ -22,6 +22,7 @@
 {{ $method := .method }}
 {{ $endpoint := .endpoint }}
 {{ $operation_data := .operation_data }}
+{{ $page := .page }}
 
 {{ $anchor := "" }}
 {{ if .anchor_base }}
@@ -29,6 +30,16 @@
 {{ end }}
 {{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }}
 
+{{/* 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 }}
+  {{ if not (reflect.IsSlice ($page.Scratch.Get "api_endpoints")) }}
+    {{ $page.Scratch.Set "api_endpoints" (slice) }}
+  {{ end }}
+  {{ $page.Scratch.Add "api_endpoints" (slice $entry) }}
+{{ end }}
+
 <section class="rendered-data">
 
 <details {{ if not site.Params.ui.rendered_data_collapsed }}open{{ end }}>

layouts/_partials/spec-content.html

@@ -0,0 +1,11 @@
+{{- /* Shared render for spec pages: title, optional description, endpoints list, body, and last-mod info. */ -}}
+<div class="td-content">
+  <h1>{{ .Title }}</h1>
+  {{ with .Params.description }}<p class="page-description">{{ . | markdownify }}</p>{{ end }}
+
+  {{ partial "endpoints-toc.html" . }}
+
+  {{ .Content }}
+
+  {{ partial "page-meta-lastmod.html" . }}
+</div>

layouts/_shortcodes/http-api.html

@@ -30,4 +30,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) }}
+{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base "page" .Page) }}

layouts/content.html

@@ -1,4 +1,3 @@
-<div class="td-content">
+{{ define "main" }}
-	<h1>{{ .Title }}</h1>
+  {{ partial "spec-content.html" . }}
-	{{ .Content }}
+{{ end }}
-</div>

layouts/docs/list.html

@@ -7,7 +7,8 @@
 {{ define "main" }}
 <div class="td-content">
 	<h1>{{ .Title }}</h1>
-        {{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
+        {{ with .Params.description }}<p class="page-description">{{ . | markdownify }}</p>{{ end }}
+        {{ partial "endpoints-toc.html" . }}
 	{{ .Content }}
 </div>
 {{ end }}

layouts/docs/single.html

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