Fix links in data

data/api/client-server/administrative_contact.yaml

@@ -183,7 +183,7 @@ paths:
     post:
       summary: Adds contact information to the user's account.
       description: |-
-        This API endpoint uses the `User-Interactive Authentication API`_.
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         Adds contact information to the user's account. Homeservers should use 3PIDs added
         through this endpoint for password resets instead of relying on the identity server.
@@ -424,7 +424,8 @@ paths:
         already associated with an account on this homeserver. This API should
         be used to request validation tokens when adding an email address to an
         account. This API's parameters and response are identical to that of
-        the |/register/email/requestToken|_ endpoint. The homeserver should validate
+        the [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken)
+        endpoint. The homeserver should validate
         the email itself, either by sending a validation email itself or by using
         a service it has control over.
       operationId: requestTokenTo3PIDEmail
@@ -474,7 +475,8 @@ paths:
         already associated with an account on this homeserver. This API should
         be used to request validation tokens when adding a phone number to an
         account. This API's parameters and response are identical to that of
-        the |/register/msisdn/requestToken|_ endpoint. The homeserver should validate
+        the [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken)
+        endpoint. The homeserver should validate
         the phone number itself, either by sending a validation message itself or by using
         a service it has control over.
       operationId: requestTokenTo3PIDMSISDN

data/api/client-server/banning.yaml

@@ -62,7 +62,7 @@ paths:
               reason:
                 type: string
                 description: The reason the user has been banned. This will be supplied as the
-                  `reason` on the target's updated `m.room.member`_ event.
+                  `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
             required: ["user_id"]
       responses:
         200:

data/api/client-server/content-repo.yaml

@@ -59,14 +59,14 @@ paths:
             format: byte
       responses:
         200:
-          description: The `MXC URI`_ for the uploaded content.
+          description: The [MXC URI](/client-server-api/#matrix-content-mxc-uris) for the uploaded content.
           schema:
             type: object
             required: ["content_uri"]
             properties:
               content_uri:
                 type: string
-                description: "The `MXC URI`_ to the uploaded content."
+                description: "The [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the uploaded content."
           examples:
             application/json: {
               "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
@@ -238,7 +238,7 @@ paths:
       summary: Download a thumbnail of content from the content repository
       description: |-
         Download a thumbnail of content from the content repository.
-        See the `thumbnailing <#thumbnails>`_ section for more information.
+        See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
       operationId: getContentThumbnail
       produces: ["image/jpeg", "image/png"]
       parameters:
@@ -278,7 +278,7 @@ paths:
           name: method
           x-example: "scale"
           description: |-
-            The desired resizing method. See the `thumbnailing <#thumbnails>`_
+            The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails)
             section for more information.
         - in: query
           type: boolean
@@ -390,7 +390,7 @@ paths:
               "og:image":
                 type: string
                 description: |-
-                  An `MXC URI`_ to the image. Omitted if there is no image.
+                  An [MXC URI](/client-server-api/#matrix-content-mxc-uris) to the image. Omitted if there is no image.
           examples:
             application/json: {
                 "og:title": "Matrix Blog Post",

data/api/client-server/create_room.yaml

@@ -173,7 +173,7 @@ paths:
                 type: object
                 description: |-
                   Extra keys, such as `m.federate`, to be added to the content
-                  of the `m.room.create`_ event. The server will clobber the following
+                  of the [`m.room.create`](client-server-api/#mroomcreate) event. The server will clobber the following
                   keys: `creator`, `room_version`. Future versions of the specification
                   may allow the server to clobber other keys.
               initial_state:
@@ -216,13 +216,14 @@ paths:
                 description: |-
                   This flag makes the server set the `is_direct` flag on the
                   `m.room.member` events sent to the users in `invite` and
-                  `invite_3pid`. See `Direct Messaging`_ for more information.
+                  `invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information.
               power_level_content_override:
                 title: Power Level Event Content
                 type: object
                 description: |-
                   The power level content to override in the default power level
-                  event. This object is applied on top of the generated `m.room.power_levels`_
+                  event. This object is applied on top of the generated
+                  [`m.room.power_levels`](client-server-api/#mroompower_levels)
                   event content prior to it being sent to the room. Defaults to
                   overriding nothing.
       responses:

data/api/client-server/cross_signing.yaml

@@ -33,7 +33,7 @@ paths:
       description: |-
         Publishes cross-signing keys for the user.
 
-        This API endpoint uses the `User-Interactive Authentication API`_.
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
       operationId: uploadCrossSigningKeys
       security:
         - accessToken: []

data/api/client-server/definitions/cross_signing_key.yaml

@@ -41,8 +41,8 @@ properties:
     type: object
     title: Signatures
     description: |-
-      Signatures of the key, calculated using the process described at `Signing
+      Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json).
-      JSON`_. Optional for the master key. Other keys must be signed by the
+      Optional for the master key. Other keys must be signed by the
       user\'s master key.
     example: {
         "@alice:example.com": {

data/api/client-server/definitions/device_keys.yaml

@@ -52,8 +52,7 @@ properties:
        Signatures for the device key object. A map from user ID, to a map from
        `<algorithm>:<device_id>` to the signature.
 
-       The signature is calculated using the process described at `Signing
+       The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
-       JSON`_.
     additionalProperties:
       type: object
       additionalProperties:

data/api/client-server/definitions/key_backup_data.yaml

@@ -35,7 +35,7 @@ properties:
   session_data:
     description: |-
       Algorithm-dependent data.  See the documentation for the backup
-      algorithms in `Server-side key backups`_ for more information on the
+      algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
       expected format of the data.
     type: object
     example: {

data/api/client-server/definitions/push_condition.yaml

@@ -18,7 +18,7 @@ properties:
   kind:
     type: string
     description: |-
-      The kind of condition to apply. See `conditions <#conditions>`_ for
+      The kind of condition to apply. See [conditions](/client-server-api/#conditions) for
       more information on the allowed kinds and how they work.
   key:
     type: string

data/api/client-server/definitions/room_event_filter.yaml

@@ -20,7 +20,7 @@ allOf:
       type: boolean
       description: |-
         If `true`, enables lazy-loading of membership events. See
-        `Lazy-loading room members <#lazy-loading-room-members>`_
+        [Lazy-loading room members](/client-server-api/#lazy-loading-room-members)
         for more information. Defaults to `false`.
     include_redundant_members:
       type: boolean
@@ -28,7 +28,7 @@ allOf:
         If `true`, sends all membership events for all events, even if they have already
         been sent to the client. Does not
         apply unless `lazy_load_members` is `true`. See
-        `Lazy-loading room members <#lazy-loading-room-members>`_
+        [Lazy-loading room members](/client-server-api/#lazy-loading-room-members)
         for more information. Defaults to `false`.
     not_rooms:
       description: A list of room IDs to exclude. If this list is absent then no rooms

data/api/client-server/definitions/user_identifier.yaml

@@ -18,7 +18,7 @@ type: object
 properties:
   type:
     type: string
-    description: The type of identification.  See `Identifier types`_ for supported values and additional property descriptions.
+    description: The type of identification.  See [Identifier types](/client-server-api/#identifier-types) for supported values and additional property descriptions.
 required:
   - type
 additionalProperties: true

data/api/client-server/device_management.yaml

@@ -137,7 +137,7 @@ paths:
     delete:
       summary: Delete a device
       description: |-
-        This API endpoint uses the `User-Interactive Authentication API`_.
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         Deletes the given device, and invalidates any access token associated with it.
       operationId: deleteDevice
@@ -183,7 +183,7 @@ paths:
     post:
       summary: Bulk deletion of devices
       description: |-
-        This API endpoint uses the `User-Interactive Authentication API`_.
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         Deletes the given devices, and invalidates any access token associated with them.
       operationId: deleteDevices

data/api/client-server/event_context.yaml

@@ -36,7 +36,7 @@ paths:
         surrounding an event.
 
         *Note*: This endpoint supports lazy-loading of room member events. See
-        `Lazy-loading room members <#lazy-loading-room-members>`_ for more information.
+        [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information.
       operationId: getEventContext
       security:
         - accessToken: []
@@ -69,7 +69,7 @@ paths:
             be applied before or/and after the `limit` parameter - whichever the
             homeserver prefers.
 
-            See `Filtering <#filtering>`_ for more information.
+            See [Filtering](/client-server-api/#filtering) for more information.
           x-example: "66696p746572"
       responses:
         200:

data/api/client-server/inviting.yaml

@@ -33,12 +33,10 @@ paths:
     post:
       summary: Invite a user to participate in a particular room.
       description: |-
-        .. _invite-by-user-id-endpoint:
-
         *Note that there are two forms of this API, which are documented separately.
         This version of the API requires that the inviter knows the Matrix
         identifier of the invitee. The other is documented in the*
-        `third party invites section`_.
+        [third party invites section](/client-server-api/#post_matrixclientr0roomsroomidinvite-1).
 
         This API invites a user to participate in a particular room.
         They do not start participating in the room until they actually join the
@@ -50,7 +48,6 @@ paths:
         If the user was invited to the room, the homeserver will append a
         `m.room.member` event to the room.
 
-        .. _third party invites section: `invite-by-third-party-id-endpoint`_
       operationId: inviteUser
       security:
         - accessToken: []

data/api/client-server/joining.yaml

@@ -40,7 +40,8 @@ paths:
         events associated with the room until the user leaves the room.
 
         After a user has joined a room, the room will appear as an entry in the
-        response of the |/initialSync|_ and |/sync|_ APIs.
+        response of the [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync)
+        and [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs.
       operationId: joinRoomById
       security:
         - accessToken: []
@@ -116,7 +117,8 @@ paths:
         events associated with the room until the user leaves the room.
 
         After a user has joined a room, the room will appear as an entry in the
-        response of the |/initialSync|_ and |/sync|_ APIs.
+        response of the [`/initialSync`](/client-server-api/#get_matrixclientr0initialsync)
+        and [`/sync`](/client-server-api/#get_matrixclientr0sync) APIs.
       operationId: joinRoom
       security:
         - accessToken: []

data/api/client-server/key_backup.yaml

@@ -51,7 +51,7 @@ paths:
               auth_data:
                 description: |-
                   Algorithm-dependent data. See the documentation for the backup
-                  algorithms in `Server-side key backups`_ for more information on the
+                  algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
                   expected format of the data.
                 type: object
                 example: {
@@ -106,7 +106,7 @@ paths:
               auth_data:
                 description: |-
                   Algorithm-dependent data. See the documentation for the backup
-                  algorithms in `Server-side key backups`_ for more information on the
+                  algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
                   expected format of the data.
                 type: object
                 example: {
@@ -169,8 +169,9 @@ paths:
           name: version
           description: |-
             The backup version to get, as returned in the `version` parameter
-            of the response in `POST /_matrix/client/r0/room_keys/version`_ or
+            of the response in
-            this endpoint.
+            [`POST /_matrix/client/r0/room_keys/version`](/client-server/#post_matrixclientr0room_keysversion)
+            or this endpoint.
           required: true
           x-example: "1"
       responses:
@@ -188,7 +189,7 @@ paths:
               auth_data:
                 description: |-
                   Algorithm-dependent data. See the documentation for the backup
-                  algorithms in `Server-side key backups`_ for more information on the
+                  algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
                   expected format of the data.
                 type: object
                 example: {
@@ -250,9 +251,9 @@ paths:
           name: version
           description: |-
             The backup version to update, as returned in the `version`
-            parameter in the response of `POST
+            parameter in the response of
-            /_matrix/client/r0/room_keys/version`_ or `GET
+            [`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientr0room_keysversion)
-            /_matrix/client/r0/room_keys/version/{version}`_.
+            or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientr0room_keysversionversion).
           required: true
           x-example: "1"
         - in: body
@@ -272,7 +273,7 @@ paths:
               auth_data:
                 description: |-
                   Algorithm-dependent data. See the documentation for the backup
-                  algorithms in `Server-side key backups`_ for more information on the
+                  algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
                   expected format of the data.
                 type: object
                 example: {
@@ -339,9 +340,9 @@ paths:
           name: version
           description: |-
             The backup version to delete, as returned in the `version`
-            parameter in the response of `POST
+            parameter in the response of
-            /_matrix/client/r0/room_keys/version`_ or `GET
+            [`POST /_matrix/client/r0/room_keys/version`](/client-server-api/#post_matrixclientr0room_keysversion)
-            /_matrix/client/r0/room_keys/version/{version}`_.
+            or [`GET /_matrix/client/r0/room_keys/version/{version}`](/client-server-api/#get_matrixclientr0room_keysversionversion).
           required: true
           x-example: "1"
       responses:

data/api/client-server/keys.yaml

@@ -58,7 +58,7 @@ paths:
                   One-time public keys for "pre-key" messages.  The names of
                   the properties should be in the format
                   `<algorithm>:<key_id>`. The format of the key is determined
-                  by the `key algorithm <#key-algorithms>`_.
+                  by the [key algorithm](/client-server-api/#key-algorithms).
 
                   May be absent if no new one-time keys are required.
                 additionalProperties:
@@ -374,7 +374,7 @@ paths:
                   One-time keys for the queried devices. A map from user ID, to a
                   map from devices to a map from `<algorithm>:<key_id>` to the key object.
 
-                  See the `key algorithms <#key-algorithms>`_ section for information
+                  See the [key algorithms](/client-server-api/#key-algorithms) section for information
                   on the Key Object format.
                 additionalProperties:
                   type: object

data/api/client-server/kicking.yaml

@@ -65,7 +65,7 @@ paths:
                 type: string
                 description: |-
                   The reason the user has been kicked. This will be supplied as the
-                  `reason` on the target's updated `m.room.member`_ event.
+                  `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
             required: ["user_id"]
       responses:
         200:

data/api/client-server/login.yaml

@@ -77,7 +77,7 @@ paths:
         The returned access token must be associated with the `device_id`
         supplied by the client or generated by the server. The server may
         invalidate any access token previously associated with that device. See
-        `Relationship between access tokens and devices`_.
+        [Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices).
       operationId: login
       parameters:
         - in: body
@@ -118,14 +118,15 @@ paths:
               token:
                 type: string
                 description: |-
-                  Required when `type` is `m.login.token`. Part of `Token-based`_ login.
+                  Required when `type` is `m.login.token`. Part of Token-based login.
               device_id:
                 type: string
                 description: |-
                   ID of the client device. If this does not correspond to a
                   known client device, a new device will be created. The given
-                  device ID must not be the same as a `cross-signing key ID
+                  device ID must not be the same as a
-                  <#cross-signing>`_. The server will auto-generate a device_id
+                  [cross-signing](/client-server-api/#cross-signing) key ID.
+                  The server will auto-generate a device_id
                   if this is not specified.
               initial_device_display_name:
                 type: string

data/api/client-server/logout.yaml

@@ -33,7 +33,7 @@ paths:
       description: |-
         Invalidates an existing access token, so that it can no longer be used for
         authorization. The device associated with the access token is also deleted.
-        `Device keys <#device-keys>`_ for the device are deleted alongside the device.
+        [Device keys](/client-server-api/#device-keys) for the device are deleted alongside the device.
       operationId: logout
       security:
         - accessToken: []
@@ -51,10 +51,10 @@ paths:
       description: |-
         Invalidates all access tokens for a user, so that they can no longer be used for
         authorization. This includes the access token that made this request. All devices
-        for the user are also deleted. `Device keys <#device-keys>`_ for the device are
+        for the user are also deleted. [Device keys](/client-server-api/#device-keys) for the device are
         deleted alongside the device.
 
-        This endpoint does not use the `User-Interactive Authentication API`_ because
+        This endpoint does not use the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) because
         User-Interactive Authentication is designed to protect against attacks where the
         someone gets hold of a single access token then takes over the account. This
         endpoint invalidates all access tokens for the user, including the token used in

data/api/client-server/message_pagination.yaml

@@ -35,7 +35,7 @@ paths:
         pagination query parameters to paginate history in the room.
 
         *Note*: This endpoint supports lazy-loading of room member events. See
-        `Lazy-loading room members <#lazy-loading-room-members>`_ for more information.
+        [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information.
       operationId: getRoomEvents
       security:
         - accessToken: []

data/api/client-server/notifications.yaml

@@ -101,7 +101,7 @@ paths:
                       type: array
                       description: |-
                         The action(s) to perform when the conditions for this rule are met.
-                        See `Push Rules: API`_.
+                        See [Push Rules: API](/client-server-api/#push-rules-api).
                       items:
                         type:
                         - object

data/api/client-server/old_sync.yaml

@@ -35,9 +35,9 @@ paths:
         block until an event is received, or until the `timeout` is reached.
 
         This endpoint was deprecated in r0 of this specification. Clients
-        should instead call the |/sync|_ API with a `since` parameter. See
+        should instead call the [`/sync`](/client-server-api/#get_matrixclientr0sync)
-        the `migration guide
+        API with a `since` parameter. See
-        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
+        the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: getEvents
       security:
         - accessToken: []
@@ -101,9 +101,9 @@ paths:
         number of messages per room to return.
 
         This endpoint was deprecated in r0 of this specification. Clients
-        should instead call the |/sync|_ API with no `since` parameter. See
+        should instead call the [`/sync`](/client-server-api/#get_matrixclientr0sync)
-        the `migration guide
+        API with no `since` parameter. See
-        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
+        the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: initialSync
       security:
         - accessToken: []
@@ -310,8 +310,9 @@ paths:
         retrieve this event e.g. by being a member in the room for this event.
 
         This endpoint was deprecated in r0 of this specification. Clients
-        should instead call the |/rooms/{roomId}/event/{eventId}|_ API
+        should instead call the
-        or the |/rooms/{roomId}/context/{eventId}|_ API.
+        [/rooms/{roomId}/event/{eventId}](/client-server-api/#get_matrixclientr0roomsroomideventeventid) API
+        or the [/rooms/{roomId}/context/{eventId](/client-server-api/#get_matrixclientr0roomsroomidcontexteventid) API.
       operationId: getOneEvent
       security:
         - accessToken: []

data/api/client-server/openid.yaml

@@ -62,7 +62,8 @@ paths:
         200:
           description: |-
             OpenID token information. This response is nearly compatible with the
-            response documented in the `OpenID Connect 1.0 Specification <http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse>`_
+            response documented in the
+            [OpenID Connect 1.0 Specification](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse)
             with the only difference being the lack of an `id_token`. Instead,
             the Matrix homeserver's name is provided.
           examples:

data/api/client-server/pusher.yaml

@@ -135,7 +135,7 @@ paths:
     post:
       summary: Modify a pusher for this user on the homeserver.
       description: |-
-        This endpoint allows the creation, modification and deletion of `pushers`_
+        This endpoint allows the creation, modification and deletion of [pushers](/client-server-api/#push-notifications)
         for this user ID. The behaviour of this endpoint varies depending on the
         values in the JSON body.
       operationId: postPusher
@@ -231,7 +231,7 @@ paths:
                       The format to send notifications in to Push Gateways if the
                       `kind` is `http`. The details about what fields the
                       homeserver should send to the push gateway are defined in the
-                      `Push Gateway Specification`_. Currently the only format
+                      [Push Gateway Specification](/push-gateway-api/). Currently the only format
                       available is 'event_id_only'.
               append:
                 type: boolean

data/api/client-server/registration.yaml

@@ -29,7 +29,7 @@ paths:
     post:
       summary: Register for an account on this homeserver.
       description: |-
-        This API endpoint uses the `User-Interactive Authentication API`_, except in
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api), except in
         the cases where a guest account is being registered.
 
         Register for an account on this homeserver.
@@ -59,7 +59,7 @@ paths:
         The returned access token must be associated with the `device_id`
         supplied by the client or generated by the server. The server may
         invalidate any access token previously associated with that device. See
-        `Relationship between access tokens and devices`_.
+        [Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices).
 
         When registering a guest account, all parameters in the request body
         with the exception of `initial_device_display_name` MUST BE ignored
@@ -67,7 +67,7 @@ paths:
         regardless of input.
 
         Any user ID returned by this API must conform to the grammar given in the
-        `Matrix specification <../appendices.html#user-identifiers>`_.
+        [Matrix specification](/appendices/#user-identifiers).
       operationId: register
       parameters:
         - in: query
@@ -145,7 +145,7 @@ paths:
                   The fully-qualified Matrix user ID (MXID) that has been registered.
 
                   Any user ID returned by this API must conform to the grammar given in the
-                  `Matrix specification <../appendices.html#user-identifiers>`_.
+                  [Matrix specification](/appendices/#user-identifiers).
               access_token:
                 type: string
                 description: |-
@@ -321,7 +321,7 @@ paths:
       description: |-
         Changes the password for an account on this homeserver.
 
-        This API endpoint uses the `User-Interactive Authentication API`_ to
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
         ensure the user changing the password is actually the owner of the
         account.
 
@@ -352,7 +352,7 @@ paths:
                   Whether the user's other access tokens, and their associated devices, should be
                   revoked if the request succeeds. Defaults to true.
 
-                  When `false`, the server can still take advantage of `the soft logout method <#soft-logout>`_
+                  When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
                   for the user's remaining devices.
                 example: true
               auth:
@@ -389,7 +389,8 @@ paths:
         `/account/password` endpoint.
 
         This API's parameters and response are identical to that of the
-        |/register/email/requestToken|_ endpoint, except that
+        [`/register/email/requestToken`](/client-server-api/#post_matrixclientr0registeremailrequesttoken)
+        endpoint, except that
         `M_THREEPID_NOT_FOUND` may be returned if no account matching the
         given email address could be found. The server may instead send an
         email to the given address prompting the user to create an account.
@@ -397,11 +398,6 @@ paths:
 
         The homeserver should validate the email itself, either by sending a
         validation email itself or by using a service it has control over.
-
-
-        .. |/register/email/requestToken| replace:: `/register/email/requestToken`
-
-        .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
       operationId: requestTokenToResetPasswordEmail
       parameters:
         - in: body
@@ -448,7 +444,8 @@ paths:
         `/account/password` endpoint.
 
         This API's parameters and response are identical to that of the
-        |/register/msisdn/requestToken|_ endpoint, except that
+        [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientr0registermsisdnrequesttoken)
+        endpoint, except that
         `M_THREEPID_NOT_FOUND` may be returned if no account matching the
         given phone number could be found. The server may instead send the SMS
         to the given phone number prompting the user to create an account.
@@ -456,10 +453,6 @@ paths:
 
         The homeserver should validate the phone number itself, either by sending a
         validation message itself or by using a service it has control over.
-
-        .. |/register/msisdn/requestToken| replace:: `/register/msisdn/requestToken`
-
-        .. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
       operationId: requestTokenToResetPasswordMSISDN
       parameters:
         - in: body
@@ -503,7 +496,7 @@ paths:
         Deactivate the user's account, removing all ability for the user to
         login again.
 
-        This API endpoint uses the `User-Interactive Authentication API`_.
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         An access token should be submitted to this endpoint if the client has
         an active session.

data/api/client-server/room_initial_sync.yaml

@@ -22,8 +22,8 @@ paths:
 
         This endpoint was deprecated in r0 of this specification. There is no
         direct replacement; the relevant information is returned by the
-        |/sync|_ API. See the `migration guide
+        [`/sync`](/client-server-api/#get_matrixclientr0sync) API. See the
-        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
+        [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: roomInitialSync
       security:
         - accessToken: []

data/api/client-server/room_send.yaml

@@ -37,7 +37,7 @@ paths:
 
         The body of the request should be the content object of the event; the
         fields in this object will vary depending on the type of event. See
-        `Room Events`_ for the m. event specification.
+        [Room Events](/client-server-api/#room-events) for the m. event specification.
       operationId: sendMessage
       security:
         - accessToken: []

data/api/client-server/room_state.yaml

@@ -31,9 +31,6 @@ paths:
     put:
       summary: Send a state event to the given room.
       description: |
-        .. For backwards compatibility with older links...
-        .. _`put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:
-
         State events can be sent using this endpoint.  These events will be
         overwritten if `<room id>`, `<event type>` and `<state key>` all
         match.
@@ -44,7 +41,7 @@ paths:
 
         The body of the request should be the content object of the event; the
         fields in this object will vary depending on the type of event. See
-        `Room Events`_ for the `m.` event specification.
+        [Room Events](/client-server-api/#room-events) for the `m.` event specification.
 
         If the event type being sent is `m.room.canonical_alias` servers
         SHOULD ensure that any new aliases being listed in the event are valid

data/api/client-server/rooms.yaml

@@ -75,9 +75,6 @@ paths:
     get:
       summary: Get the state identified by the type and key.
       description: |-
-        .. For backwards compatibility with older links...
-        .. _`get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:
-
         Looks up the contents of a state event in a room. If the user is
         joined to the room then the state is taken from the current
         state of the room. If the user has left the room then the state is

data/api/client-server/search.yaml

@@ -90,12 +90,8 @@ paths:
                       filter:
                         type: object
                         title: Filter
-                        # Within the C-S spec document, `filter`_ is picked up
-                        # as a link to the filtering section. In OpenAPI 3.0,
-                        # we could use the link feature, but we're still on 2.0
-                        # for now :/
                         description: |-
-                          This takes a `filter`_.
+                          This takes a [filter](/client-server-api/#filtering).
                         allOf:
                           - $ref: "definitions/room_event_filter.yaml"
                       order_by:

data/api/client-server/sync.yaml

@@ -35,7 +35,7 @@ paths:
         of the state on the server, and then continue to call this API to get
         incremental deltas to the state, and to receive new messages.
 
-        *Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_
+        *Note*: This endpoint supports lazy-loading. See [Filtering](/client-server-api/#filtering)
         for more information. Lazy-loading members is only supported on a `StateFilter`
         for this endpoint. When lazy-loading is enabled, servers MUST include the
         syncing user's own membership event when they join a room, or when the
@@ -67,7 +67,7 @@ paths:
             clients that reuse the same filter multiple times, for example in
             long poll requests.
 
-            See `Filtering <#filtering>`_ for more information.
+            See [Filtering](/client-server-api/#filtering) for more information.
           x-example: "66696p746572"
         - in: query
           name: since
@@ -236,7 +236,7 @@ paths:
                           type: object
                           description: |-
                             Counts of unread notifications for this room. See the
-                            `Receiving notifications section <#receiving-notifications>`_
+                            [Receiving notifications](/client-server-api/#receiving-notifications) section
                             for more information on how these are calculated.
                           properties:
                             highlight_count:
@@ -333,13 +333,13 @@ paths:
                 type: object
                 description: |-
                   Information on the send-to-device messages for the client
-                  device, as defined in |send_to_device_sync|_.
+                  device, as defined in [Send-to-Device messaging](/client-server-api/#extensions-to-sync).
               device_lists:
                 title: DeviceLists
                 type: object
                 description: |-
                   Information on end-to-end device updates, as specified in
-                  |device_lists_sync|_.
+                  [End-to-end encryption](/client-server-api/#extensions-to-sync-1).
               device_one_time_keys_count:
                 title: One-time keys count
                 type: object
@@ -347,7 +347,7 @@ paths:
                   type: integer
                 description: |-
                   Information on end-to-end encryption keys, as specified
-                  in |device_lists_sync|_.
+                  in [End-to-end encryption](/client-server-api/#extensions-to-sync-1).
             required:
               - next_batch
           examples:

data/api/client-server/third_party_membership.yaml

@@ -31,14 +31,12 @@ paths:
     post:
       summary: Invite a user to participate in a particular room.
       description: |-
-        .. _invite-by-third-party-id-endpoint:
-
         *Note that there are two forms of this API, which are documented separately.
         This version of the API does not require that the inviter know the Matrix
         identifier of the invitee, and instead relies on third party identifiers.
         The homeserver uses an identity server to perform the mapping from
         third party identifier to a Matrix identifier. The other is documented in the*
-        `joining rooms section`_.
+        [joining rooms section](/client-server-api/#post_matrixclientr0roomsroomidinvite).
 
         This API invites a user to participate in a particular room.
         They do not start participating in the room until they actually join the
@@ -74,7 +72,6 @@ paths:
         If a token is requested from the identity server, the homeserver will
         append a `m.room.third_party_invite` event to the room.
 
-        .. _joining rooms section: `invite-by-user-id-endpoint`_
       operationId: inviteBy3PID
       security:
         - accessToken: []

data/api/identity/associations.yaml

@@ -258,7 +258,7 @@ paths:
                   medium:
                     type: string
                     description: |-
-                      A medium from the `3PID Types`_ Appendix, matching the medium
+                      A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium
                       of the identifier to unbind.
                   address:
                     type: string

data/api/identity/invitation_signing.yaml

@@ -53,7 +53,7 @@ paths:
                 description: The token from the call to `store-invite`.
               private_key:
                 type: string
-                description: The private key, encoded as `Unpadded base64`_.
+                description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64).
             required: ["mxid", "token", "private_key"]
       responses:
         200:

data/api/identity/lookup.yaml

@@ -38,13 +38,13 @@ paths:
           type: string
           name: medium
           required: true
-          description: The medium type of the 3pid. See the `3PID Types`_ Appendix.
+          description: The medium type of the 3pid. See the [3PID Types](/appendices/#3pid-types) Appendix.
           x-example: "email"
         - in: query
           type: string
           name: address
           required: true
-          description: The address of the 3pid being looked up. See the `3PID Types`_ Appendix.
+          description: The address of the 3pid being looked up. See the [3PID Types](/appendices/#3pid-types) Appendix.
           x-example: "louise@bobs.burgers"
       responses:
         200:
@@ -72,7 +72,7 @@ paths:
                 description: The 3pid address of the user being looked up, matching the address requested.
               medium:
                 type: string
-                description: A medium from the `3PID Types`_ Appendix, matching the medium requested.
+                description: A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium requested.
               mxid:
                 type: string
                 description: The Matrix user ID associated with the 3pid.
@@ -131,7 +131,7 @@ paths:
                     - type: string
                     - type: string
                 description: |-
-                  An array of arrays containing the `3PID Types`_ with the `medium`
+                  An array of arrays containing the [3PID Types](/appendices/#3pid-types) with the `medium`
                   in first position and the `address` in second position.
             required:
               - "threepids"
@@ -164,7 +164,7 @@ paths:
                     - type: string
                     - type: string
                 description: |-
-                  An array of array containing the `3PID Types`_ with the `medium`
+                  An array of array containing the [3PID Types](/appendices/#3pid-types) with the `medium`
                   in first position, the `address` in second position and Matrix user
                   ID in third position.
             required:

data/api/identity/v2_associations.yaml

@@ -98,7 +98,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",
@@ -222,7 +222,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",
@@ -286,7 +286,7 @@ paths:
                   medium:
                     type: string
                     description: |-
-                      A medium from the `3PID Types`_ Appendix, matching the medium
+                      A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium
                       of the identifier to unbind.
                   address:
                     type: string
@@ -318,7 +318,7 @@ paths:
             unbinding identifiers).
 
             Another common error code is `M_TERMS_NOT_SIGNED` where the user
-            needs to `agree to more terms`_ in order to continue.
+            needs to [agree to more terms](/identity-service-api/#terms-of-service) in order to continue.
           examples:
             application/json: {
               "errcode": "M_FORBIDDEN",

data/api/identity/v2_auth.yaml

@@ -83,7 +83,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",
@@ -121,7 +121,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",

data/api/identity/v2_email_associations.yaml

@@ -77,7 +77,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",
@@ -149,7 +149,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",
@@ -206,7 +206,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",

data/api/identity/v2_invitation_signing.yaml

@@ -57,7 +57,7 @@ paths:
                 description: The token from the call to `store-invite`.
               private_key:
                 type: string
-                description: The private key, encoded as `Unpadded base64`_.
+                description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64).
             required: ["mxid", "token", "private_key"]
       responses:
         200:
@@ -102,7 +102,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",

data/api/identity/v2_phone_associations.yaml

@@ -79,7 +79,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",
@@ -151,7 +151,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",
@@ -208,7 +208,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",

data/api/identity/v2_store_invite.yaml

@@ -166,7 +166,7 @@ paths:
         403:
           description: |
             The user must do something in order to use this endpoint. One example
-            is an `M_TERMS_NOT_SIGNED` error where the user must `agree to more terms`_.
+            is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
           examples:
             application/json: {
               "errcode": "M_TERMS_NOT_SIGNED",

data/api/server-server/backfill.yaml

@@ -130,7 +130,7 @@ paths:
                 type: array
                 description: |-
                   The missing events. The event format varies depending on the room version - check
-                  the `room version specification`_ for precise event formats.
+                  the [room version specification](/#room-versions) for precise event formats.
                 items:
                   type: object
                   title: PDU

data/api/server-server/definitions/invite_event.yaml

@@ -15,7 +15,7 @@ type: object
 title: InviteEvent
 description: |-
   An invite event. Note that events have a different format depending on the
-  room version - check the `room version specification`_ for precise event formats.
+  room version - check the [room version specification](/#room-versions) for precise event formats.
 allOf:
   - type: object
     properties:
@@ -46,7 +46,7 @@ allOf:
         title: Membership Event Content
         description: |-
           The content of the event, matching what is available in the
-          `Client-Server API`_. Must include a `membership` of `invite`.
+          [Client-Server API](/client-server-api/). Must include a `membership` of `invite`.
         example: {"membership": "invite"}
         properties:
           membership:

data/api/server-server/definitions/keys.yaml

@@ -41,7 +41,7 @@ properties:
       properties:
         key:
           type: string
-          description: The `Unpadded Base64`_ encoded key.
+          description: The [Unpadded base64](/appendices/#unpadded-base64) encoded key.
           example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
       required: ["key"]
   old_verify_keys:
@@ -70,7 +70,7 @@ properties:
           example: 1532645052628
         key:
           type: string
-          description: The `Unpadded Base64`_ encoded key.
+          description: The [Unpadded base64](/appendices/#unpadded-base64) encoded key.
           example: "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
       required: ["expired_ts", "key"]
   signatures:
@@ -78,8 +78,7 @@ properties:
     description: |-
       Digital signatures for this object signed using the `verify_keys`.
 
-      The signature is calculated using the process described at `Signing
+      The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
-      JSON`_.
     title: Signatures
     additionalProperties:
       type: object
@@ -91,7 +90,7 @@ properties:
     description: |-
       POSIX timestamp when the list of valid keys should be refreshed. This field MUST
       be ignored in room versions 1, 2, 3, and 4. Keys used beyond this timestamp MUST
-      be considered invalid, depending on the `room version specification`_.
+      be considered invalid, depending on the [room version specification](/#room-versions).
 
       Servers MUST use the lesser of this field and 7 days into the future when
       determining if a key is valid. This is to avoid a situation where an attacker

data/api/server-server/definitions/pdu.yaml

@@ -24,7 +24,7 @@ allOf:
         type: object
         title: Event Hash
         description: |-
-          Content hashes of the PDU, following the algorithm specified in `Signing Events`_.
+          Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
         example: {
           "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted"
         }
@@ -37,7 +37,7 @@ allOf:
       signatures:
         type: object
         description: |-
-          Signatures for the PDU, following the algorithm specified in `Signing Events`_.
+          Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
         example: {
           "example.com": {
             "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"

data/api/server-server/definitions/pdu_v3.yaml

@@ -52,7 +52,7 @@ allOf:
         type: object
         title: Event Hash
         description: |-
-          Content hashes of the PDU, following the algorithm specified in `Signing Events`_.
+          Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
         example: {
           "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted"
         }
@@ -65,7 +65,7 @@ allOf:
       signatures:
         type: object
         description: |-
-          Signatures for the PDU, following the algorithm specified in `Signing Events`_.
+          Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
         example: {
           "example.com": {
             "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"

data/api/server-server/definitions/security.yaml

@@ -14,6 +14,6 @@
 signedRequest:
   type: apiKey
   description: |-
-    The `Authorization` header defined in the `Authentication`_ section.
+    The `Authorization` header defined in the [Authentication](/server-server-api/#authentication) section.
   name: Authorization
   in: header

data/api/server-server/definitions/send_join_response.yaml

@@ -25,13 +25,13 @@ properties:
       The auth chain for the entire current room state prior to the join event.
 
       Note that events have a different format depending on the room version - check the
-      `room version specification`_ for precise event formats.
+      [room version specification](/#room-versions) for precise event formats.
     items:
       type: object
       title: PDU
       description: |-
-        The `PDUs <#pdus>`_ that make up the auth chain. The event format varies depending
+        The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending
-        on the room version - check the `room version specification`_ for precise event formats.
+        on the room version - check the [room version specification](/#room-versions) for precise event formats.
       schema:
         type: object
         properties: []
@@ -42,14 +42,14 @@ properties:
     description: |-
       The resolved current room state prior to the join event.
 
-      The event format varies depending on the room version - check the `room version specification`_
+      The event format varies depending on the room version - check the [room version specification](/#room-versions)
       for precise event formats.
     items:
       type: object
       title: PDU
       description: |-
-        The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending
+        The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending
-        on the room version - check the `room version specification`_ for precise event formats.
+        on the room version - check the [room version specification](/#room-versions) for precise event formats.
       schema:
         type: object
         properties: []

data/api/server-server/definitions/single_pdu_transaction.yaml

@@ -19,13 +19,13 @@ properties:
     type: array
     description: |-
       A single PDU. Note that events have a different format depending on the room
-      version - check the `room version specification`_ for precise event formats.
+      version - check the [room version specification](/#room-versions) for precise event formats.
     items:
       type: object
       title: PDU
       description: |-
-        The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
+        The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending
-        on the room version - check the `room version specification`_ for precise event formats.
+        on the room version - check the [room version specification](/#room-versions) for precise event formats.
       properties: []
       example:
         $ref: "../examples/minimal_pdu.json"

data/api/server-server/definitions/transaction.yaml

@@ -34,13 +34,13 @@ properties:
     description: |-
       List of persistent updates to rooms. Must not include more than 50 PDUs. Note that
       events have a different format depending on the room version - check the
-      `room version specification`_ for precise event formats.
+      [room version specification](/#room-versions) for precise event formats.
     items:
       type: object
       title: PDU
       description: |-
-        The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
+        The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending
-        on the room version - check the `room version specification`_ for precise event formats.
+        on the room version - check the [room version specification](/#room-versions) for precise event formats.
       properties: []
       example:
         $ref: "../examples/minimal_pdu.json"

data/api/server-server/definitions/unlimited_pdu_transaction.yaml

@@ -19,14 +19,14 @@ properties:
     type: array
     description: |-
       List of persistent updates to rooms. Note that events have a different format
-      depending on the room version - check the `room version specification`_ for
+      depending on the room version - check the [room version specification](/#room-versions) for
       precise event formats.
     items:
       type: object
       title: PDU
       description: |-
-        The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
+        The [PDUs](/server-server-api/#pdus) contained in the transaction. The event format varies depending
-        on the room version - check the `room version specification`_ for precise event formats.
+        on the room version - check the [room version specification](/#room-versions) for precise event formats.
       properties: []
       example:
         $ref: "../examples/minimal_pdu.json"

data/api/server-server/event_auth.yaml

@@ -60,13 +60,13 @@ paths:
                   The full set of authorization events that make up the state of
                   the room, and their authorization events, recursively. Note that
                   events have a different format depending on the room version -
-                  check the `room version specification`_ for precise event formats.
+                  check the [room version specification](/#room-versions) for precise event formats.
                 items:
                   type: object
                   title: PDU
                   description: |-
-                    The `PDUs <#pdus>`_ contained in the auth chain. The event format
+                    The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format
-                    varies depending on the room version - check the `room version specification`_
+                    varies depending on the room version - check the [room version specification](/#room-versions)
                     for precise event formats.
                   properties: []
                   example:

data/api/server-server/events.yaml

@@ -61,13 +61,13 @@ paths:
                   The full set of authorization events that make up the state
                   of the room, and their authorization events, recursively. Note that
                   events have a different format depending on the room version -
-                  check the `room version specification`_ for precise event formats.
+                  check the [room version specification](/#room-versions) for precise event formats.
                 items:
                   type: object
                   title: PDU
                   description: |-
-                    The `PDUs <#pdus>`_ contained in the auth chain. The event format
+                    The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format
-                    varies depending on the room version - check the `room version specification`_
+                    varies depending on the room version - check the [room version specification](/#room-versions)
                     for precise event formats.
                   properties: []
                   example:
@@ -77,13 +77,13 @@ paths:
                 description: |-
                   The fully resolved state of the room at the given event. Note that
                   events have a different format depending on the room version -
-                  check the `room version specification`_ for precise event formats.
+                  check the [room version specification](/#room-versions) for precise event formats.
                 items:
                   type: object
                   title: PDU
                   description: |-
-                    The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format
+                    The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format
-                    varies depending on the room version - check the `room version specification`_
+                    varies depending on the room version - check the [room version specification](/#room-versions)
                     for precise event formats.
                   properties: []
                   example:

data/api/server-server/invites-v1.yaml

@@ -40,7 +40,7 @@ paths:
         or `"2"`.
 
         Note that events have a different format depending on the room version - check the
-        `room version specification`_ for precise event formats. **The request and response
+        [room version specification](/#room-versions) for precise event formats. **The request and response
         bodies here describe the common event fields in more detail and may be missing other
         required fields for a PDU.**
       operationId: sendInviteV1
@@ -106,7 +106,7 @@ paths:
           description: |-
             The event with the invited server's signature added. All other fields of the events
             should remain untouched. Note that events have a different format depending on the
-            room version - check the `room version specification`_ for precise event formats.
+            room version - check the [room version specification](/#room-versions) for precise event formats.
           schema:
             type: array
             minItems: 2

data/api/server-server/invites-v2.yaml

@@ -44,7 +44,7 @@ paths:
         API as the server may be older, if the room version is "1" or "2".
 
         Note that events have a different format depending on the room version - check the
-        `room version specification`_ for precise event formats. **The request and response
+        [room version specification](/#room-versions) for precise event formats. **The request and response
         bodies here describe the common event fields in more detail and may be missing other
         required fields for a PDU.**
       operationId: sendInviteV2
@@ -111,7 +111,7 @@ paths:
           description: |-
             The event with the invited server's signature added. All other fields of the events
             should remain untouched. Note that events have a different format depending on the
-            room version - check the `room version specification`_ for precise event formats.
+            room version - check the [room version specification](/#room-versions) for precise event formats.
           schema:
             type: object
             description: An object containing the signed invite event.

data/api/server-server/joins-v1.yaml

@@ -62,9 +62,9 @@ paths:
       responses:
         200:
           description: |-
-            A template to be used for the rest of the `Joining Rooms`_ handshake. Note that
+            A template to be used for the rest of the [Joining Rooms](/server-server-api/#joining-rooms) handshake. Note that
             events have a different format depending on the room version - check the
-            `room version specification`_ for precise event formats. **The response body
+            [room version specification](/#room-versions) for precise event formats. **The response body
             here describes the common event fields in more detail and may be missing other
             required fields for a PDU.**
           schema:
@@ -79,7 +79,7 @@ paths:
               event:
                 description: |-
                   An unsigned template event. Note that events have a different format
-                  depending on the room version - check the `room version specification`_
+                  depending on the room version - check the [room version specification](/#room-versions)
                   for precise event formats.
                 type: object
                 title: Event Template
@@ -182,7 +182,7 @@ paths:
         Submits a signed join event to the resident server for it
         to accept it into the room's graph. Note that events have
         a different format depending on the room version - check
-        the `room version specification`_ for precise event formats.
+        the [room version specification](/#room-versions) for precise event formats.
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**

data/api/server-server/joins-v2.yaml

@@ -45,7 +45,7 @@ paths:
         Submits a signed join event to the resident server for it
         to accept it into the room's graph. Note that events have
         a different format depending on the room version - check
-        the `room version specification`_ for precise event formats.
+        the [room version specification](/#room-versions) for precise event formats.
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**

data/api/server-server/leaving-v1.yaml

@@ -55,7 +55,7 @@ paths:
           description: |-
             A template to be used to call `/send_leave`. Note that
             events have a different format depending on the room version - check the
-            `room version specification`_ for precise event formats. **The response body
+            [room version specification](/#room-versions) for precise event formats. **The response body
             here describes the common event fields in more detail and may be missing other
             required fields for a PDU.**
           schema:
@@ -70,7 +70,7 @@ paths:
               event:
                 description: |-
                   An unsigned template event. Note that events have a different format
-                  depending on the room version - check the `room version specification`_
+                  depending on the room version - check the [room version specification](/#room-versions)
                   for precise event formats.
                 type: object
                 title: Event Template
@@ -149,7 +149,7 @@ paths:
         Submits a signed leave event to the resident server for it
         to accept it into the room's graph. Note that events have
         a different format depending on the room version - check
-        the `room version specification`_ for precise event formats.
+        the [room version specification](/#room-versions) for precise event formats.
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**

data/api/server-server/leaving-v2.yaml

@@ -45,7 +45,7 @@ paths:
         Submits a signed leave event to the resident server for it
         to accept it into the room's graph. Note that events have
         a different format depending on the room version - check
-        the `room version specification`_ for precise event formats.
+        the [room version specification](/#room-versions) for precise event formats.
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**

data/api/server-server/third_party_invite.yaml

@@ -33,7 +33,7 @@ paths:
       description: |-
         The receiving server will verify the partial `m.room.member` event
         given in the request body. If valid, the receiving server will issue
-        an invite as per the `Inviting to a room`_ section before returning a
+        an invite as per the [Inviting to a room](/server-server-api/#inviting-to-a-room) section before returning a
         response to this request.
       operationId: exchangeThirdPartyInvite
       security:
@@ -111,7 +111,7 @@ paths:
                               The server signatures for this event.
 
                               The signature is calculated using the process
-                              described at `Signing JSON`_.
+                              described at [Signing JSON](/appendices/#signing-json).
                             example: {
                               "magic.forest": {
                                 "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"

data/api/server-server/transactions.yaml

@@ -39,7 +39,7 @@ paths:
         transaction with a different `txnId` to the receiving server.
 
         Note that events have a different format depending on the room version - check
-        the `room version specification`_ for precise event formats.
+        the [room version specification](/#room-versions) for precise event formats.
       operationId: sendTransaction
       security:
         - signedRequest: []

data/api/server-server/user_keys.yaml

@@ -74,7 +74,7 @@ paths:
                   One-time keys for the queried devices. A map from user ID, to a
                   map from devices to a map from `<algorithm>:<key_id>` to the key object.
 
-                  See the `Client-Server Key Algorithms`_ section for more information on
+                  See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on
                   the Key Object format.
                 additionalProperties:
                   type: object
@@ -97,8 +97,7 @@ paths:
                             description: |-
                               Signature of the key object.
 
-                              The signature is calculated using the process described at `Signing
+                              The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
-                              JSON`_.
                         required: ['key', 'signatures']
                 example: {
                   "@alice:example.com": {

data/api/server-server/wellknown.yaml

@@ -50,4 +50,4 @@ paths:
                 description: |-
                   The server name to delegate server-server communciations to, with optional
                   port. The delegated server name uses the same grammar as
-                  `server names in the appendices <../appendices.html#server-name>`_.
+                  [server names in the appendices](/appendices/#server-name).

data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml

@@ -19,13 +19,14 @@ properties:
     type: integer
   thumbnail_url:
     description: |-
-      The URL (typically `MXC URI`_) to a thumbnail of the image.
+      The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris)) to a thumbnail of the image.
       Only present if the thumbnail is unencrypted.
     type: string
   thumbnail_file:
     description: |-
       Information on the encrypted thumbnail file, as specified in
-      |encrypted_files|_. Only present if the thumbnail is encrypted.
+      [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
+      Only present if the thumbnail is encrypted.
     title: EncryptedFile
     type: object
   thumbnail_info:

data/event-schemas/schema/m.dummy.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   This event type is used to indicate new Olm sessions for end-to-end encryption.
-  Typically it is encrypted as an `m.room.encrypted` event, then sent as a `to-device`_
+  Typically it is encrypted as an `m.room.encrypted` event, then sent as a [to-device](/client-server-api/#send-to-device-messaging)
   event.
 
   The event does not have any content associated with it. The sending client is expected

data/event-schemas/schema/m.forwarded_room_key.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   This event type is used to forward keys for end-to-end encryption. Typically
-  it is encrypted as an `m.room.encrypted` event, then sent as a `to-device`_
+  it is encrypted as an `m.room.encrypted` event, then sent as a [to-device](/client-server-api/#send-to-device-messaging)
   event.
 properties:
   content:
@@ -48,7 +48,7 @@ properties:
         description: |-
           Indicates that the key cannot be used to decrypt all the messages
           from the session because a portion of the session was withheld as
-          described in `Reporting that decryption keys are withheld`_. This
+          described in [Reporting that decryption keys are withheld](/client-server-api/#reporting-that-decryption-keys-are-withheld). This
           object must include the `code` and `reason` properties from the
           `m.room_key.withheld` message that was received by the sender of
           this message.

data/event-schemas/schema/m.key.verification.accept.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   Accepts a previously sent `m.key.verification.start` message. Typically sent as a
-  `to-device`_ event.
+  [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties:

data/event-schemas/schema/m.key.verification.cancel.yaml

@@ -3,7 +3,7 @@ allOf:
   - $ref: core-event-schema/event.yaml
 
 description: |-
-  Cancels a key verification process/request. Typically sent as a `to-device`_ event.
+  Cancels a key verification process/request. Typically sent as a [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties:

data/event-schemas/schema/m.key.verification.key.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   Sends the ephemeral public key for a device to the partner device. Typically sent as a
-  `to-device`_ event.
+  [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties:

data/event-schemas/schema/m.key.verification.mac.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   Sends the MAC of a device's key to the partner device. Typically sent as a
-  `to-device`_ event.
+  [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties:

data/event-schemas/schema/m.key.verification.request.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   Requests a key verification with another user's devices. Typically sent as a
-  `to-device`_ event.
+  [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties:

data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml

@@ -3,7 +3,7 @@ allOf:
   - $ref: core-event-schema/event.yaml
 
 description: |-
-  Begins a SAS key verification process using the `m.sas.v1` method. Typically sent as a `to-device`_ event.
+  Begins a SAS key verification process using the `m.sas.v1` method. Typically sent as a [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties:

data/event-schemas/schema/m.key.verification.start.yaml

@@ -3,7 +3,7 @@ allOf:
   - $ref: core-event-schema/event.yaml
 
 description: |-
-  Begins a key verification process. Typically sent as a `to-device`_ event. The `method`
+  Begins a key verification process. Typically sent as a [to-device](/client-server-api/#send-to-device-messaging) event. The `method`
   field determines the type of verification. The fields in the event will differ depending
   on the `method`. This definition includes fields that are in common among all variants.
 properties:

data/event-schemas/schema/m.room.encrypted.yaml

@@ -4,8 +4,8 @@ allOf:
 
 description: |-
   This event type is used when sending encrypted events. It can be used either
-  within a room (in which case it will have all of the `Room Event fields`_), or
+  within a room (in which case it will have all of the [Room Event fields](/client-server-api/#room-event-fields)), or
-  as a `to-device`_ event.
+  as a [to-device](/client-server-api/#send-to-device-messaging) event.
 
 properties:
   content:
@@ -37,7 +37,7 @@ properties:
           The encrypted content of the event. Either the encrypted payload
           itself, in the case of a Megolm event, or a map from the recipient
           Curve25519 identity key to ciphertext information, in the case of an
-          Olm event. For more details, see `Messaging Algorithms`_.
+          Olm event. For more details, see [Messaging Algorithms](/client-server-api/#messaging-algorithms).
       sender_key:
         type: string
         description: The Curve25519 key of the sender.

data/event-schemas/schema/m.room.member.yaml

@@ -65,7 +65,7 @@ properties:
           - ban
         type: string
       is_direct:
-        description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See `Direct Messaging`_.
+        description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
         type: boolean
       reason:
         type: string

data/event-schemas/schema/m.room.message$m.audio.yaml

@@ -28,13 +28,14 @@ properties:
         type: string
       url:
         description: |-
-          Required if the file is unencrypted. The URL (typically `MXC URI`_)
+          Required if the file is unencrypted. The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris))
           to the audio clip.
         type: string
       file:
         description: |-
           Required if the file is encrypted. Information on the encrypted
-          file, as specified in |encrypted_files|_.
+          file, as specified in
+          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
         title: EncryptedFile
         type: object
     required:

data/event-schemas/schema/m.room.message$m.file.yaml

@@ -28,7 +28,8 @@ properties:
           thumbnail_file:
             description: |-
               Information on the encrypted thumbnail file, as specified in
-              |encrypted_files|_. Only present if the thumbnail is encrypted.
+              [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
+              Only present if the thumbnail is encrypted.
             title: EncryptedFile
             type: object
           thumbnail_info:
@@ -43,13 +44,14 @@ properties:
         type: string
       url:
         description: |-
-          Required if the file is unencrypted. The URL (typically `MXC URI`_)
+          Required if the file is unencrypted. The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris))
           to the file.
         type: string
       file:
         description: |-
           Required if the file is encrypted. Information on the encrypted
-          file, as specified in |encrypted_files|_.
+          file, as specified in
+          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
         title: EncryptedFile
         type: object
     required:

data/event-schemas/schema/m.room.message$m.image.yaml

@@ -18,13 +18,14 @@ properties:
         type: string
       url:
         description: |-
-          Required if the file is unencrypted. The URL (typically `MXC URI`_)
+          Required if the file is unencrypted. The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris))
           to the image.
         type: string
       file:
         description: |-
           Required if the file is encrypted. Information on the encrypted
-          file, as specified in |encrypted_files|_.
+          file, as specified in
+          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
         title: EncryptedFile
         type: object
     required:

data/event-schemas/schema/m.room.message$m.location.yaml

@@ -26,7 +26,8 @@ properties:
           thumbnail_file:
             description: |-
               Information on the encrypted thumbnail file, as specified in
-              |encrypted_files|_. Only present if the thumbnail is encrypted.
+              [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
+              Only present if the thumbnail is encrypted.
             title: EncryptedFile
             type: object
           thumbnail_info:

data/event-schemas/schema/m.room.message$m.video.yaml

@@ -28,13 +28,14 @@ properties:
             type: integer
           thumbnail_url:
             description: |-
-              The URL (typically `MXC URI`_) to an image thumbnail of
+              The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris)) to an image thumbnail of
               the video clip. Only present if the thumbnail is unencrypted.
             type: string
           thumbnail_file:
             description: |-
               Information on the encrypted thumbnail file, as specified in
-              |encrypted_files|_. Only present if the thumbnail is encrypted.
+              [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
+              Only present if the thumbnail is encrypted.
             title: EncryptedFile
             type: object
           thumbnail_info:
@@ -49,13 +50,14 @@ properties:
         type: string
       url:
         description: |-
-          Required if the file is unencrypted. The URL (typically `MXC URI`_)
+          Required if the file is unencrypted. The URL (typically [MXC URI](/client-server-api/#matrix-content-mxc-uris))
           to the video clip.
         type: string
       file:
         description: |-
           Required if the file is encrypted. Information on the encrypted
-          file, as specified in |encrypted_files|_.
+          file, as specified in
+          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
         title: EncryptedFile
         type: object
     required:

data/event-schemas/schema/m.room.message.feedback.yaml

@@ -1,7 +1,7 @@
 ---
 allOf:
   - $ref: core-event-schema/room_event.yaml
-description: '**NB: Usage of this event is discouraged in favour of the** `receipts module`_. **Most clients will not recognise this event.** Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: `delivered` (sent when the event has been received) and `read` (sent when the event has been observed by the end-user). The `target_event_id` should reference the `m.room.message` event being acknowledged.'
+description: '**NB: Usage of this event is discouraged in favour of the** [receipts module](/client-server-api/#receipts). **Most clients will not recognise this event.** Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: `delivered` (sent when the event has been received) and `read` (sent when the event has been observed by the end-user). The `target_event_id` should reference the `m.room.message` event being acknowledged.'
 properties:
   content:
     properties:

data/event-schemas/schema/m.room_key.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   This event type is used to exchange keys for end-to-end encryption. Typically
-  it is encrypted as an `m.room.encrypted` event, then sent as a `to-device`_ event.
+  it is encrypted as an `m.room.encrypted` event, then sent as a [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties:

data/event-schemas/schema/m.room_key_request.yaml

@@ -4,7 +4,7 @@ allOf:
 
 description: |-
   This event type is used to request keys for end-to-end encryption. It is sent as an
-  unencrypted `to-device`_ event.
+  unencrypted [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties: