Merge branch 'main' into rename-custom-formats

Signed-off-by: Kévin Commaille <[email protected]>

.github/workflows/main.yml

@@ -255,7 +255,7 @@ jobs:
       - name: "Run htmltest"
         uses: wjdp/htmltest-action@master
         with:
-          config: .htmltest.yaml
+          config: .htmltest.yml
 
   build-historical-spec:
     name: "📖 Build the historical backup spec"

assets/scss/_styles_project.scss

@@ -26,12 +26,6 @@ Custom SCSS for the Matrix spec
  */
 @import "syntax.scss";
 
-/* Workaround for https://github.com/google/docsy/issues/1116:
- * fix scroll-anchoring */
-.td-outer {
-    height: auto;
-}
-
 /* Overrides for the navbar */
 .td-navbar {
   box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
@@ -387,6 +381,11 @@ footer {
       border-top: 1px $table-border-color solid;
     }
 
+    td > p:last-child {
+      // Avoid unnecessary space at the bottom of the cells.
+      margin-bottom: 0;
+    }
+
     &.object-table, &.response-table, &.content-type-table {
         border: 1px $table-border-color solid;
 

changelogs/client_server/newsfragments/1967.clarification

@@ -0,0 +1 @@
+Sort VoIP events semantically.

changelogs/client_server/newsfragments/1973.clarification

@@ -0,0 +1 @@
+Clarify that servers must forward custom keys in `PusherData` when sending notifications to the push gateway.

changelogs/internal/newsfragments/1967.clarification

@@ -0,0 +1 @@
+Add `x-weight` property for sorting events rendered with the `event-group` shortcode.

changelogs/internal/newsfragments/1969.clarification

@@ -0,0 +1 @@
+Enforce consistent vertical spacing between paragraphs in endpoint definitions.

changelogs/internal/newsfragments/1975.clarification

@@ -0,0 +1 @@
+Fix formatting of `added-in` and `changed-in` shortcodes by using `%` delimiter.

changelogs/internal/newsfragments/1976.clarification

@@ -0,0 +1 @@
+Remove CSS workaround for scroll-anchoring.

changelogs/internal/newsfragments/1985.clarification

@@ -0,0 +1 @@
+Rename `.htmltest.yaml` to `.htmltest.yml`.

changelogs/push_gateway/newsfragments/1968.clarification

@@ -0,0 +1 @@
+Document the schema of `PusherData`.

changelogs/server_server/newsfragments/1926.clarification

@@ -0,0 +1 @@
+Add 403 error response to `/_matrix/federation/v1/state_ids/{roomId}`.

content/appendices.md

@@ -761,7 +761,7 @@ wish to consider handling them as `u`, `r`, and `e` respectively.
 {{% /boxes/note %}}
 
 {{% boxes/note %}}
-{{< changed-in v="1.11" >}}
+{{% changed-in v="1.11" %}}
 Referencing event IDs within a room identified by room alias (`r`) rather than room ID
 (`roomid`) is now deprecated.  We are not aware of these ever having been used in
 practice, and are nonsensical given room aliases are mutable.
@@ -858,7 +858,7 @@ Examples of matrix.to URIs are:
 * Link to `@alice:example.org`: `https://matrix.to/#/%40alice%3Aexample.org`
 
 {{% boxes/note %}}
-{{< changed-in v="1.11" >}}
+{{% changed-in v="1.11" %}}
 Referencing event IDs within a room identified by room alias rather than room ID
 is now deprecated.  We are not aware of these ever having been used in
 practice, and are nonsensical given room aliases are mutable.

content/client-server-api/_index.md

@@ -242,7 +242,8 @@ The `retry_after_ms` property MAY be included to tell the client how long
 they have to wait in milliseconds before they can try again. This property is
 deprecated, in favour of the `Retry-After` header.
 
-{{< changed-in v="1.10" >}}: `retry_after_ms` property deprecated in favour of `Retry-After` header.
+{{% changed-in v="1.10" %}}: `retry_after_ms` property deprecated in favour of `Retry-After` header.
+
 ### Transaction identifiers
 
 The client-server API typically uses `HTTP PUT` to submit requests with
@@ -436,7 +437,7 @@ could mean one of four things:
 1. the access token was never valid.
 2. the access token has been logged out.
 3. the access token has been [soft logged out](#soft-logout).
-4. {{< added-in v="1.3" >}} the access token [needs to be refreshed](#refreshing-access-tokens).
+4. {{% added-in v="1.3" %}} the access token [needs to be refreshed](#refreshing-access-tokens).
 
 When a client receives an error code of `M_UNKNOWN_TOKEN`, it should:
 
@@ -1350,7 +1351,7 @@ client supports it, the client should redirect the user to the
 is complete, the client will need to submit a `/login` request matching
 `m.login.token`.
 
-{{< added-in v="1.7" >}} Already-authenticated clients can additionally generate
+{{% added-in v="1.7" %}} Already-authenticated clients can additionally generate
 a token for their user ID if supported by the homeserver using
 [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
 
@@ -2342,7 +2343,7 @@ The endpoints where the server *should* include bundled aggregations are:
 * [`GET /sync`](#get_matrixclientv3sync) when the relevant section has a `limited` value
   of `true`.
 * [`POST /search`](#post_matrixclientv3search) for any matching events under `room_events`.
-* {{< added-in v="1.4" >}} [`GET /rooms/{roomId}/threads`](#get_matrixclientv1roomsroomidthreads)
+* {{% added-in v="1.4" %}} [`GET /rooms/{roomId}/threads`](#get_matrixclientv1roomsroomidthreads)
 
 {{% boxes/note %}}
 The server is **not** required to return bundled aggregations on deprecated endpoints

content/client-server-api/modules/content_repo.md

@@ -16,12 +16,12 @@ When serving content, the server SHOULD provide a
 `Content-Security-Policy` header. The recommended policy is
 `sandbox; default-src 'none'; script-src 'none'; plugin-types application/pdf; style-src 'unsafe-inline'; object-src 'self';`.
 
-{{< added-in v="1.4" >}} The server SHOULD additionally provide
+{{% added-in v="1.4" %}} The server SHOULD additionally provide
 `Cross-Origin-Resource-Policy: cross-origin` when serving content to allow
 (web) clients to access restricted APIs such as `SharedArrayBuffer` when
 interacting with the media repository.
 
-{{< changed-in v="1.11" >}} The unauthenticated download endpoints have been
+{{% changed-in v="1.11" %}} The unauthenticated download endpoints have been
 deprecated in favour of newer, authenticated, ones. This change includes updating
 the paths of all media endpoints from `/_matrix/media/*` to `/_matrix/client/{version}/media/*`,
 with the exception of the `/upload` and `/create` endpoints. The upload/create
@@ -44,7 +44,7 @@ mxc://<server-name>/<media-id>
 
 Clients can access the content repository using the following endpoints.
 
-{{< changed-in v="1.11" >}} A number of endpoints under the /_matrix/media hierarchy
+{{% changed-in v="1.11" %}} A number of endpoints under the /_matrix/media hierarchy
 have been deprecated and replaced with new endpoints which require authentication.
 The deprecated endpoints are marked in the section below.
 

content/client-server-api/modules/event_replacements.md

@@ -188,7 +188,7 @@ replacement event.
 
 ##### Server-side aggregation of `m.replace` relationships
 
-{{< changed-in v="1.7" >}}
+{{% changed-in v="1.7" %}}
 
 Note that there can be multiple events with an `m.replace` relationship to a
 given event (for example, if an event is edited multiple times). These should

content/client-server-api/modules/guest_access.md

@@ -40,13 +40,13 @@ for retrieving events and associated media:
 * [GET /rooms/{roomId}/event/{eventId}](#get_matrixclientv3roomsroomideventeventid)
 * [GET /rooms/{roomId}/state/{eventType}/{stateKey}](#get_matrixclientv3roomsroomidstateeventtypestatekey)
 * [GET /rooms/{roomId}/messages](#get_matrixclientv3roomsroomidmessages)
-* {{< added-in v="1.1" >}} [GET /rooms/{roomId}/members](#get_matrixclientv3roomsroomidmembers)
+* {{% added-in v="1.1" %}} [GET /rooms/{roomId}/members](#get_matrixclientv3roomsroomidmembers)
 * [GET /rooms/{roomId}/initialSync](#get_matrixclientv3roomsroomidinitialsync)
 * [GET /sync](#get_matrixclientv3sync)
 * [GET /events](#get_matrixclientv3events) as used for room previews.
-* {{< added-in v="1.12" >}} [GET /media/download/{serverName}/{mediaId}](#get_matrixclientv1mediadownloadservernamemediaid)
-* {{< added-in v="1.12" >}} [GET /media/download/{serverName}/{mediaId}/{fileName}](#get_matrixclientv1mediadownloadservernamemediaidfilename)
-* {{< added-in v="1.12" >}} [GET /media/thumbnail/{serverName}/{mediaId}](#get_matrixclientv1mediathumbnailservernamemediaid)
+* {{% added-in v="1.12" %}} [GET /media/download/{serverName}/{mediaId}](#get_matrixclientv1mediadownloadservernamemediaid)
+* {{% added-in v="1.12" %}} [GET /media/download/{serverName}/{mediaId}/{fileName}](#get_matrixclientv1mediadownloadservernamemediaidfilename)
+* {{% added-in v="1.12" %}} [GET /media/thumbnail/{serverName}/{mediaId}](#get_matrixclientv1mediathumbnailservernamemediaid)
 
 The following API endpoints are allowed to be accessed by guest accounts
 for sending events:
@@ -55,9 +55,9 @@ for sending events:
 * [POST /rooms/{roomId}/leave](#post_matrixclientv3roomsroomidleave)
 * [PUT /rooms/{roomId}/send/{eventType}/{txnId}](#put_matrixclientv3roomsroomidsendeventtypetxnid)
 
-    * {{< changed-in v="1.2" >}} Guests can now send *any* event type rather than just `m.room.message` events.
+    * {{% changed-in v="1.2" %}} Guests can now send *any* event type rather than just `m.room.message` events.
 
-* {{< added-in v="1.2" >}} [PUT /rooms/{roomId}/state/{eventType}/{stateKey}](#put_matrixclientv3roomsroomidstateeventtypestatekey)
+* {{% added-in v="1.2" %}} [PUT /rooms/{roomId}/state/{eventType}/{stateKey}](#put_matrixclientv3roomsroomidstateeventtypestatekey)
 * [PUT /sendToDevice/{eventType}/{txnId}](#put_matrixclientv3sendtodeviceeventtypetxnid)
 
 The following API endpoints are allowed to be accessed by guest accounts
@@ -67,7 +67,7 @@ for their own account maintenance:
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)
-* {{< added-in v="1.2" >}} [GET /account/whoami](#get_matrixclientv3accountwhoami)
+* {{% added-in v="1.2" %}} [GET /account/whoami](#get_matrixclientv3accountwhoami)
 
 The following API endpoints are allowed to be accessed by guest accounts
 for end-to-end encryption:

content/client-server-api/modules/push.md

@@ -525,7 +525,7 @@ Definition:
 
 <a id="_m_rule_is_user_mention"></a> **`.m.rule.is_user_mention`**
 
-{{< added-in v="1.7" >}}
+{{% added-in v="1.7" %}}
 
 Matches any message which contains the user's Matrix ID in the list of `user_ids`
 under the `m.mentions` property.
@@ -594,7 +594,7 @@ Definition:
 
 <a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**
 
-{{< added-in v="1.7" >}}
+{{% added-in v="1.7" %}}
 
 Matches any message from a sender with the proper power level with the `room`
 property of the `m.mentions` property set to `true`.
@@ -1072,7 +1072,7 @@ ahead), however if the `m.read.private` receipt were to be updated to
 event D then the user has read up to D (the `m.read` receipt is now
 behind the `m.read.private` receipt).
 
-{{< added-in v="1.4" >}} When handling threaded read receipts, the server is to
+{{% added-in v="1.4" %}} When handling threaded read receipts, the server is to
 partition the notification count to each thread (with the main timeline being
 its own thread). To determine if an event is part of a thread the server follows
 the [event relationship](#forming-relationships-between-events) until it finds a

content/client-server-api/modules/read_markers.md

@@ -29,7 +29,7 @@ The client cannot update fully read markers by directly modifying the
 `m.fully_read` account data event. Instead, the client must make use of
 the read markers API to change the values.
 
-{{< changed-in v="1.4" >}} `m.read.private` receipts can now be sent from
+{{% changed-in v="1.4" %}} `m.read.private` receipts can now be sent from
 `/read_markers`.
 
 The read markers API can additionally update the user's read receipt

content/client-server-api/modules/receipts.md

@@ -1,7 +1,7 @@
 
 ### Receipts
 
-{{< changed-in v="1.4" >}} Added private read receipts.
+{{% changed-in v="1.4" %}} Added private read receipts.
 
 This module adds in support for receipts. These receipts are a form of
 acknowledgement of an event. This module defines the `m.read` receipt
@@ -19,7 +19,7 @@ that the user had read all events *up to* the referenced event. See the
 [Receiving notifications](#receiving-notifications) section for more
 information on how read receipts affect notification counts.
 
-{{< added-in v="1.4" >}} Read receipts exist in three major forms:
+{{% added-in v="1.4" %}} Read receipts exist in three major forms:
 * Unthreaded: Denotes a read-up-to receipt regardless of threads. This is how
   pre-threading read receipts worked.
 * Threaded, main timeline: Denotes a read-up-to receipt for events not in a
@@ -31,15 +31,15 @@ Threaded read receipts are discussed in further detail [below](#threaded-read-re
 
 #### Events
 
-{{< changed-in v="1.4" >}} Each `user_id`, `receipt_type`, and categorisation
+{{% changed-in v="1.4" %}} Each `user_id`, `receipt_type`, and categorisation
 (unthreaded, or `thread_id`) tuple must be associated with only a single
 `event_id`.
 
 {{% event event="m.receipt" %}}
 
 #### Client behaviour
 
-{{< changed-in v="1.4" >}} Altered to support threaded read receipts.
+{{% changed-in v="1.4" %}} Altered to support threaded read receipts.
 
 In `/sync`, receipts are listed under the `ephemeral` array of events
 for a given room. New receipts that come down the event streams are

content/client-server-api/modules/report_content.md

@@ -21,11 +21,11 @@ rooms instead of individual events. Server administrators and safety teams
 should, therefore, be cautious not to shut down rooms that might otherwise
 be legitimate.
 
-{{< changed-in v="1.8" >}} When processing event reports, servers MUST
+{{% changed-in v="1.8" %}} When processing event reports, servers MUST
 verify that the reporting user is currently joined to the room the event
 is in before accepting a report.
 
-{{< added-in v="1.12" >}} Contrarily, servers MUST NOT restrict room reports
+{{% added-in v="1.12" %}} Contrarily, servers MUST NOT restrict room reports
 based on whether or not the reporting user is joined to the room. This is
 because users can be exposed to harmful content without being joined to a
 room. For instance, through room directories or invites.

content/client-server-api/modules/room_upgrades.md

@@ -30,7 +30,7 @@ server:
 1.  Checks that the user has permission to send `m.room.tombstone`
     events in the room.
 
-2.  {{< changed-in v="1.4" >}} Creates a replacement room with a `m.room.create` event containing a
+2.  {{% changed-in v="1.4" %}} Creates a replacement room with a `m.room.create` event containing a
     `predecessor` field, the applicable `room_version`, and a `type` field
     which is copied from the `predecessor` room. If no `type` is set on the
     previous room, no `type` is specified on the new room's create event

content/rooms/fragments/v3-auth-rules.md

@@ -1,6 +1,6 @@
 ---
 ---
-{{< added-in v=3 >}} In room versions 1 and 2, events need a
+{{% added-in v=3 %}} In room versions 1 and 2, events need a
 signature from the domain of the `event_id` in order to be considered
 valid. This room version does not include an `event_id` over federation
 in the same respect, so does not need a signature from that server.

content/rooms/fragments/v8-auth-rules.md

@@ -54,7 +54,7 @@ The rules are as follows:
 4.  If type is `m.room.member`:
     1.  If there is no `state_key` property, or no `membership` property in
         `content`, reject.
-    2.  {{< added-in v=8 >}}
+    2.  {{% added-in v=8 %}}
         If `content` has a `join_authorised_via_users_server` property:
         1.  If the event is not validly signed by the homeserver of the user ID denoted
             by the key, reject.
@@ -65,7 +65,7 @@ The rules are as follows:
         3.  If the `sender` is banned, reject.
         4.  If the `join_rule` is `invite` or `knock` then allow if
             membership state is `invite` or `join`.
-        5.  {{< added-in v=8 >}}
+        5.  {{% added-in v=8 %}}
             If the `join_rule` is `restricted`:
             1.  If membership state is `join` or `invite`, allow.
             2.  If the `join_authorised_via_users_server` key in `content`

content/rooms/v10.md

@@ -141,7 +141,7 @@ The rules are as follows:
         3.  If the `sender` is banned, reject.
         4.  If the `join_rule` is `invite` or `knock` then allow if
             membership state is `invite` or `join`.
-        5.  {{< changed-in v=10 >}}
+        5.  {{% changed-in v=10 %}}
             If the `join_rule` is `restricted` or `knock_restricted`:
             1.  If membership state is `join` or `invite`, allow.
             2.  If the `join_authorised_via_users_server` key in `content`
@@ -197,7 +197,7 @@ The rules are as follows:
             than the `sender`'s power level, allow.
         3.  Otherwise, reject.
     7. If `membership` is `knock`:
-        1.  {{< changed-in v=10 >}}
+        1.  {{% changed-in v=10 %}}
             If the `join_rule` is anything other than `knock` or
             `knock_restricted`, reject.
         2.  If `sender` does not match `state_key`, reject.
@@ -214,11 +214,11 @@ The rules are as follows:
 8.  If the event has a `state_key` that starts with an `@` and does not
     match the `sender`, reject.
 9. If type is `m.room.power_levels`:
-    1.  {{< added-in v=10 >}}
+    1.  {{% added-in v=10 %}}
         If any of the properties `users_default`, `events_default`, `state_default`,
         `ban`, `redact`, `kick`, or `invite` in `content` are present and
         not an integer, reject.
-    2.  {{< added-in v=10 >}}
+    2.  {{% added-in v=10 %}}
         If either of the properties `events` or `notifications` in `content`
         are present and not an object with values that are integers,
         reject.

content/rooms/v11.md

@@ -12,7 +12,7 @@ rules.
 
 ### Redactions
 
-{{< added-in v=11 >}} The top-level `origin`, `membership`, and `prev_state` properties
+{{% added-in v=11 %}} The top-level `origin`, `membership`, and `prev_state` properties
 are no longer protected from redaction. The [`m.room.create`](/client-server-api#mroomcreate)
 event now keeps the entire `content` property. The [`m.room.redaction`](/client-server-api#mroomredaction)
 event keeps the `redacts` property under `content`. The
@@ -112,7 +112,7 @@ the [Handling redactions](#handling-redactions) section.
 
 The rules are as follows:
 
-1.  {{< changed-in v=11 >}}
+1.  {{% changed-in v=11 %}}
     If type is `m.room.create`:
     1.  If it has any `prev_events`, reject.
     2.  If the domain of the `room_id` does not match the domain of the
@@ -142,7 +142,7 @@ The rules are as follows:
         1.  If the event is not validly signed by the homeserver of the user ID denoted
             by the key, reject.
     3.  If `membership` is `join`:
-        1.  {{< changed-in v=11 >}}
+        1.  {{% changed-in v=11 %}}
             If the only previous event is an `m.room.create` and the
             `state_key` is the sender, allow.
         2.  If the `sender` does not match `state_key`, reject.

content/rooms/v3.md

@@ -90,7 +90,7 @@ The complete structure of a event in a v3 room is shown below.
 ### Authorization rules
 
 {{% boxes/note %}}
-{{< added-in v=3 >}} `m.room.redaction` events are subject to auth rules in
+{{% added-in v=3 %}} `m.room.redaction` events are subject to auth rules in
 the same way as any other event. In practice, that means they will normally be allowed
 by the auth rules, unless the `m.room.power_levels` event sets a power level requirement
 for `m.room.redaction`events via the `events` or `events_default` properties. In