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

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,48 +2,45 @@
 title: "Server-Server API"
 weight: 20
 type: docs
----
+description: |
+  Matrix homeservers use the Federation APIs (also known as server-server APIs)
+  to communicate with each other. Homeservers use these APIs to push messages in
+  real-time, retrieve historic messages, and query profile or presence
+  information about users on other servers. The APIs are implemented over HTTPS,
+  with authentication provided by public key signatures both at the TLS
+  transport layer and in HTTP Authorization headers.
+
+  There are three main kinds of communication that occur between
+  homeservers:
+
+  Persistent Data Units (PDUs):
+  These events are broadcast from one homeserver to any others that have
+  joined the same room (identified by Room ID). They are persisted in
+  long-term storage and record the history of messages and state for a
+  room.
+
+  Like email, it is the responsibility of the originating server of a PDU
+  to deliver that event to its recipient servers. However PDUs are signed
+  using the originating server's private key so that it is possible to
+  deliver them through third-party servers.
+
+  Ephemeral Data Units (EDUs):
+  These events are pushed between pairs of homeservers. They are not
+  persisted and are not part of the history of a room, nor does the
+  receiving homeserver have to reply to them.
+
+  Queries:
+  These are single request/response interactions between a given pair of
+  servers, initiated by one side sending an HTTPS GET request to obtain
+  some information, and responded by the other. They are not persisted and
+  contain no long-term significant history. They simply request a snapshot
+  state at the instant the query is made.
+
+  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.
 
-Matrix homeservers use the Federation APIs (also known as server-server
-APIs) to communicate with each other. Homeservers use these APIs to push
-messages to each other in real-time, to retrieve historic messages from
-each other, and to query profile and presence information about users on
-each other's servers.
-
-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:
-
-Persistent Data Units (PDUs):
-These events are broadcast from one homeserver to any others that have
-joined the same room (identified by Room ID). They are persisted in
-long-term storage and record the history of messages and state for a
-room.
-
-Like email, it is the responsibility of the originating server of a PDU
-to deliver that event to its recipient servers. However PDUs are signed
-using the originating server's private key so that it is possible to
-deliver them through third-party servers.
-
-Ephemeral Data Units (EDUs):
-These events are pushed between pairs of homeservers. They are not
-persisted and are not part of the history of a room, nor does the
-receiving homeserver have to reply to them.
-
-Queries:
-These are single request/response interactions between a given pair of
-servers, initiated by one side sending an HTTPS GET request to obtain
-some information, and responded by the other. They are not persisted and
-contain no long-term significant history. They simply request a snapshot
-state at the instant the query is made.
-
-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
 

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