Move each spec's intro above the endpoints list

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

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/spec-content.html

@@ -1,6 +1,8 @@
 {{- /* 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 }}