Merge bb54e7d303 into 6edb6ba1cd

* Clarify that SSO login applies to the legacy authentication API

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Do not point to specific authentication API for obtaining access token

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add warnings about incompatibility with OAuth 2.0 to endpoints that use UIA

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add note about API standards not applying to OAuth 2.0

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Apply suggestions from code review

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Travis Ralston <travpc@gmail.com>

.github/workflows/main.yml

@@ -1,7 +1,7 @@
 name: "Spec"
 
 env:
-  HUGO_VERSION: 0.139.0
+  HUGO_VERSION: 0.147.8
   PYTHON_VERSION: 3.13
 
 on:

README.md

@@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
 
 1. Install the extended version (often the OS default) of Hugo:
    <https://gohugo.io/getting-started/installing>. Note that at least Hugo
-   v0.123.1 is required.
+   v0.146.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required

changelogs/application_service/newsfragments/2130.feature

@@ -1 +0,0 @@
-Correct null value handling for the AS Registration's `url` property.

changelogs/client_server/newsfragments/2068.clarification

@@ -1 +0,0 @@
-Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty.

changelogs/client_server/newsfragments/2077.clarification

@@ -1 +0,0 @@
-Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places.

changelogs/client_server/newsfragments/2083.clarification

@@ -1,2 +0,0 @@
-Clarify the format of third-party invites, including the fact that identity
-server public keys can be encoded using standard or URL-safe base64.

changelogs/client_server/newsfragments/2095.feature

@@ -1 +0,0 @@
-Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).

changelogs/client_server/newsfragments/2101.clarification

@@ -1 +0,0 @@
-"Public" rooms in profile look-ups are defined through their join rule and history visibility.

changelogs/client_server/newsfragments/2102.clarification

@@ -1 +0,0 @@
-"Public" rooms in user directory queries are defined through their join rule and history visibility.

changelogs/client_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/client_server/newsfragments/2106.clarification

@@ -1 +0,0 @@
-"Public" rooms with respect to call invites are defined through their join rule.

changelogs/client_server/newsfragments/2107.clarification

@@ -1 +0,0 @@
-"Public" rooms have no specific meaning with respect to moderation policy lists.

changelogs/client_server/newsfragments/2108.clarification

@@ -1 +0,0 @@
-"Public" rooms with respect to presence are defined through their join rule.

changelogs/client_server/newsfragments/2109.clarification

@@ -1 +0,0 @@
-Spaces are subject to the same access mechanisms as rooms.

changelogs/client_server/newsfragments/2121.clarification

@@ -1 +0,0 @@
-Fix various typos throughout the specification.

changelogs/client_server/newsfragments/2122.feature

@@ -1 +0,0 @@
-Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147).

changelogs/client_server/newsfragments/2125.feature

@@ -1 +0,0 @@
-Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/client_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2141.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2144.clarification

@@ -1 +0,0 @@
-Fix typo: as->has.

changelogs/client_server/newsfragments/2147.new

@@ -1 +0,0 @@
-Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965).

changelogs/client_server/newsfragments/2148.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2149.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2150.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2151.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2154.clarification

@@ -1 +0,0 @@
-Add missing fields in example for `ExportedSessionData`.

changelogs/client_server/newsfragments/2158.feature

@@ -1 +0,0 @@
-Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/client_server/newsfragments/2159.feature

@@ -1 +0,0 @@
-Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/identity_service/newsfragments/2083.clarification

@@ -1 +0,0 @@
-Clarify that public keys can be encoded using standard or URL-safe base64.

changelogs/internal/newsfragments/2081.clarification

@@ -1 +0,0 @@
-Adjust margins in rendered endpoints.

changelogs/internal/newsfragments/2088.clarification

@@ -1 +0,0 @@
-Replace Hugo shortcodes in OpenAPI output.

changelogs/internal/newsfragments/2115.clarification

@@ -1 +0,0 @@
-Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks.

changelogs/internal/newsfragments/2123.clarification

@@ -1 +0,0 @@
-Fix the historical info box when generating the historical spec in CI.

changelogs/internal/newsfragments/2137.clarification

@@ -1 +0,0 @@
-Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks.

changelogs/internal/newsfragments/2160.clarification

@@ -0,0 +1 @@
+Upgrade the docsy theme to version 0.12.0.

changelogs/server_server/newsfragments/2067.clarification

@@ -1 +0,0 @@
-Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room.

changelogs/server_server/newsfragments/2083.clarification

@@ -1,2 +0,0 @@
-Clarify the format of third-party invites, including the fact that identity
-server public keys can be encoded using standard or URL-safe base64.

changelogs/server_server/newsfragments/2095.feature

@@ -1 +0,0 @@
-Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).

changelogs/server_server/newsfragments/2100.clarification

@@ -1 +0,0 @@
-Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`.

changelogs/server_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/server_server/newsfragments/2125.feature

@@ -1 +0,0 @@
-Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

changelogs/server_server/newsfragments/2128.clarification

@@ -1 +0,0 @@
-Fix various typos throughout the specification.

changelogs/server_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

config/_default/hugo.toml

@@ -8,7 +8,7 @@ enableRobotsTXT = true
 # We disable RSS, because (a) it's useless, (b) Hugo seems to generate broken
 # links to it when used with a --baseURL (for example, https://spec.matrix.org/v1.4/
 # contains `<link rel="alternate" type="application/rss&#43;xml" href="/v1.4/v1.4/index.xml">`).
-disableKinds = ["taxonomy", "RSS"]
+disableKinds = ["taxonomy", "rss"]
 
 [languages]
 [languages.en]
@@ -67,7 +67,7 @@ current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec.
 # major = "1"
-# minor = "14"
+# minor = "15"
 
 # User interface configuration
 [params.ui]
@@ -134,7 +134,7 @@ sidebar_menu_compact = true
 [module]
   [module.hugoVersion]
     extended = true
-    min = "0.123.1"
+    min = "0.146.0"
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false

content/changelog/_index.md

@@ -1,6 +1,7 @@
 ---
 title: Changelog
 type: docs
+layout: changelog-index
 weight: 1000
 ---
 

content/changelog/v1.15.md

@@ -0,0 +1,97 @@
+---
+title: v1.15 Changelog
+linkTitle: v1.15
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-06-26
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `GET /_matrix/client/v1/room_summary/{roomIdOrAlias}`, as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+- Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965). ([#2147](https://github.com/matrix-org/matrix-spec/issues/2147))
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147). ([#2122](https://github.com/matrix-org/matrix-spec/issues/2122))
+- Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125), [#2158](https://github.com/matrix-org/matrix-spec/issues/2158))
+- Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals. ([#2141](https://github.com/matrix-org/matrix-spec/issues/2141), [#2148](https://github.com/matrix-org/matrix-spec/issues/2148), [#2149](https://github.com/matrix-org/matrix-spec/issues/2149), [#2150](https://github.com/matrix-org/matrix-spec/issues/2150), [#2151](https://github.com/matrix-org/matrix-spec/issues/2151), [#2159](https://github.com/matrix-org/matrix-spec/issues/2159), [#2164](https://github.com/matrix-org/matrix-spec/issues/2164))
+
+**Spec Clarifications**
+
+- Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty. ([#2068](https://github.com/matrix-org/matrix-spec/issues/2068))
+- Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places. ([#2077](https://github.com/matrix-org/matrix-spec/issues/2077))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- "Public" rooms in profile look-ups are defined through their join rule and history visibility. ([#2101](https://github.com/matrix-org/matrix-spec/issues/2101))
+- "Public" rooms in user directory queries are defined through their join rule and history visibility. ([#2102](https://github.com/matrix-org/matrix-spec/issues/2102))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- "Public" rooms with respect to call invites are defined through their join rule. ([#2106](https://github.com/matrix-org/matrix-spec/issues/2106))
+- "Public" rooms have no specific meaning with respect to moderation policy lists. ([#2107](https://github.com/matrix-org/matrix-spec/issues/2107))
+- "Public" rooms with respect to presence are defined through their join rule. ([#2108](https://github.com/matrix-org/matrix-spec/issues/2108))
+- Spaces are subject to the same access mechanisms as rooms. ([#2109](https://github.com/matrix-org/matrix-spec/issues/2109))
+- Fix various typos throughout the specification. ([#2121](https://github.com/matrix-org/matrix-spec/issues/2121), [#2144](https://github.com/matrix-org/matrix-spec/issues/2144))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+- Add missing fields in example for `ExportedSessionData`. ([#2154](https://github.com/matrix-org/matrix-spec/issues/2154))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+
+**Spec Clarifications**
+
+- Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room. ([#2067](https://github.com/matrix-org/matrix-spec/issues/2067))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`. ([#2100](https://github.com/matrix-org/matrix-spec/issues/2100))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- Fix various typos throughout the specification. ([#2128](https://github.com/matrix-org/matrix-spec/issues/2128))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Clarify in the application service registration schema the `url: null` behaviour. ([#2130](https://github.com/matrix-org/matrix-spec/issues/2130))
+
+
+## Identity Service API
+
+**Spec Clarifications**
+
+- Clarify that public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+No significant changes.
+
+
+## Appendices
+
+No significant changes.
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Adjust margins in rendered endpoints. ([#2081](https://github.com/matrix-org/matrix-spec/issues/2081))
+- Replace Hugo shortcodes in OpenAPI output. ([#2088](https://github.com/matrix-org/matrix-spec/issues/2088))
+- Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks. ([#2115](https://github.com/matrix-org/matrix-spec/issues/2115))
+- Fix the historical info box when generating the historical spec in CI. ([#2123](https://github.com/matrix-org/matrix-spec/issues/2123))
+- Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks. ([#2137](https://github.com/matrix-org/matrix-spec/issues/2137))

content/client-server-api/_index.md

@@ -12,6 +12,12 @@ clients which maintain a full local persistent copy of server state.
 
 ## API Standards
 
+{{% boxes/note %}}
+These standards only apply to the APIs defined in the Matrix specification. APIs
+used by this specification but defined in other specifications, like the [OAuth
+2.0 API](#oauth-20-api), use their own rules.
+{{% /boxes/note %}}
+
 The mandatory baseline for client-server communication in Matrix is
 exchanging JSON objects over HTTP APIs. More efficient transports may be
 specified in future as optional extensions.

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

@@ -6,9 +6,10 @@ allow users to log into applications via a single web-based
 authentication portal. Examples include OpenID Connect, "Central
 Authentication Service" (CAS) and SAML.
 
-This module allows a Matrix homeserver to delegate user authentication
+This module allows a Matrix homeserver that supports the [legacy authentication
-to an external authentication server supporting one of these protocols.
+API](#legacy-api) to delegate user authentication to an external authentication
-In this process, there are three systems involved:
+server supporting one of these protocols. In this process, there are three
+systems involved:
 
 -   A Matrix client, using the APIs defined in this specification, which
     is seeking to authenticate a user to a Matrix homeserver.
@@ -24,7 +25,7 @@ used to communicate with the authentication server. Different Matrix
 homeserver implementations might support different SSO protocols.
 
 Clients and homeservers implementing the SSO flow will need to consider
-both [login](#login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
+both [login](#legacy-login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
 similar in both cases, but there are slight differences.
 
 Typically, SSO systems require a single "callback" URI to be configured

content/proposals.md

@@ -185,6 +185,10 @@ is as follows:
     -   Take care in creating your proposal. Specify your intended
         changes, and give reasoning to back them up. Changes without
         justification will likely be poorly received by the community.
+    -   At the time of creating your draft you will not yet know the PR number, so you
+        should use a placeholder number to name your file and edit that
+        after PR submission. The suggested steps are described in
+        detail [in the proposals guide](https://github.com/matrix-org/matrix-spec-proposals#1-writing-the-proposal).
 -   Fork and make a PR to the
     [matrix-spec-proposals](https://github.com/matrix-org/matrix-spec-proposals) repository.
     The ID of your PR will become the MSC ID for the lifetime of your

data/api/client-server/administrative_contact.yaml

@@ -201,6 +201,11 @@ paths:
 
         Homeservers should prevent the caller from adding a 3PID to their account if it has
         already been added to another user's account on the homeserver.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: add3PID
       security:
         - accessTokenQuery: []

data/api/client-server/cross_signing.yaml

@@ -26,7 +26,7 @@ paths:
         Publishes cross-signing keys for the user.
 
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
-        
+
         User-Interactive Authentication MUST be performed, except in these cases:
         - there is no existing cross-signing master key uploaded to the homeserver, OR
         - there is an existing cross-signing master key and it exactly matches the
@@ -34,11 +34,16 @@ paths:
           keys provided in the request (self-signing key, user-signing key) they MUST also
           match the existing keys stored on the server. In other words, the request contains
           no new keys.
-        
+
         This allows clients to freely upload one set of keys, but not modify/overwrite keys if
-        they already exist. Allowing clients to upload the same set of keys more than once 
+        they already exist. Allowing clients to upload the same set of keys more than once
         makes this endpoint idempotent in the case where the response is lost over the network,
         which would otherwise cause a UIA challenge upon retry.
+
+        {{% boxes/warning %}}
+        When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: uploadCrossSigningKeys
       security:
         - accessTokenQuery: []

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

@@ -14,8 +14,8 @@
 accessTokenQuery:
   type: apiKey
   description: |-
-    **Deprecated.** The `access_token` returned by a call to `/login` or `/register`, as a query
+    **Deprecated.** The `access_token` obtained during [account registration](/client-server-api/#account-registration)
-    parameter.
+    or [login](/client-server-api/#login), as a query parameter.
 
     It can also be the `as_token` of an application service.
   name: access_token
@@ -23,11 +23,11 @@ accessTokenQuery:
 accessTokenBearer:
   type: http
   description: |-
-    The `access_token` returned by a call to `/login` or `/register`, using the
+    The `access_token` obtained during [account registration](/client-server-api/#account-registration)
-    `Authorization: Bearer` header.
+    or [login](/client-server-api/#login), using the `Authorization: Bearer` header.
 
     It can also be the `as_token` of an application service.
-    
+
     This is the preferred method.
   scheme: bearer
 appserviceAccessTokenQuery:
@@ -42,6 +42,6 @@ appserviceAccessTokenBearer:
   description: |-
     The `as_token` of an application service, using the `Authorization: Bearer`
     header.
-    
+
     This is the preferred method.
   scheme: bearer

data/api/client-server/device_management.yaml

@@ -137,6 +137,11 @@ paths:
         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.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: deleteDevice
       security:
         - accessTokenQuery: []
@@ -189,6 +194,11 @@ paths:
         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.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: deleteDevices
       security:
         - accessTokenQuery: []

go.mod

@@ -3,3 +3,5 @@ module github.com/matrix-org/matrix-spec
 go 1.12
 
 require github.com/matrix-org/docsy v0.0.0-20241106102557-ec7b98ee4014 // indirect
+
+replace github.com/matrix-org/docsy => github.com/zecakeh/matrix-org-docsy v0.0.0-20250609083047-3b5e81464c1d

go.sum

@@ -1,4 +1,4 @@
-github.com/FortAwesome/Font-Awesome v0.0.0-20240716171331-37eff7fa00de/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
+github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
-github.com/matrix-org/docsy v0.0.0-20241106102557-ec7b98ee4014 h1:CNvxuuURuxkEjA0QN+lRKELc7PRDsX270e8v4GDF3II=
+github.com/twbs/bootstrap v5.3.6+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
-github.com/matrix-org/docsy v0.0.0-20241106102557-ec7b98ee4014/go.mod h1:4Ek1bcdbfU/j8hIatEjNhIs1Yua85FtQf3kLvoYZ0bQ=
+github.com/zecakeh/matrix-org-docsy v0.0.0-20250609083047-3b5e81464c1d h1:yO1JdmvpuDBWHxYVDhRZeKElcEWyzW5VmR1p6vcjQPA=
-github.com/twbs/bootstrap v5.3.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
+github.com/zecakeh/matrix-org-docsy v0.0.0-20250609083047-3b5e81464c1d/go.mod h1:4/t21g/nPraob/DVMm3jrk26k0CDL5I7Mxf+ar0IAgs=

layouts/_default/_markup/td-heading-self-link.html

@@ -1,11 +0,0 @@
-{{- /*
-
-    A simplified copy of the inlined "_default/_markup/_td-heading-self-link.html"
-    template in Docsy's "_default/_markup/td-render-heading.html" template to be
-    able to reuse it when the heading has custom markup.
-
-    Takes a string which is the ID of the heading.
-
-*/ -}}
-
-<a class="td-heading-self-link" href="#{{ . | safeURL }}" aria-label="Heading self-link"></a>

layouts/_markup/render-heading.html

@@ -8,4 +8,4 @@
     heading.
 
 */ -}}
-{{ template "_default/_markup/td-render-heading.html" . }}
+{{ partial "td/render-heading.html" . }}

layouts/_partials/events/render-event.html

@@ -24,7 +24,7 @@
 
   <h1 id="{{ $anchor }}">
    {{ with .title }}{{ . | markdownify }}{{ else }}<code>{{ $event_name }}</code>{{ end }}
-   {{ template "_default/_markup/td-heading-self-link.html" $anchor }}
+   {{ partial "td/heading-self-link.html" (dict "Anchor" $anchor) }}
   </h1>
 
 </summary>

layouts/_partials/json-schema/resolve-additional-types.html

@@ -66,7 +66,7 @@
  *     If the input `schema` was itself an object that we should create a table for,
  *     this will be the same as the first entry in `objects`.
  */
-{{ define "partials/resolve-additional-types-inner" }}
+{{ define "_partials/resolve-additional-types-inner" }}
     {{ $this_object := .schema }}
     {{ $anchor_base := .anchor_base }}
     {{ $name := .name }}
@@ -222,7 +222,7 @@
  *   * `objects`: The array of object schema definitions.
  *   * `schema`: An updated copy of the `schema` input (eg, an `anchor` may be added).
  */
-{{ define "partials/get-additional-objects" }}
+{{ define "_partials/get-additional-objects" }}
     /* .name is the name of the object for logging purposes */
     {{ $name := .name }}
 
@@ -246,6 +246,6 @@
  * This is needed for uniqify to work - otherwise objects that are the same
  * but with (for example) different examples will be considered different.
  */
-{{ define "partials/clean-object" }}
+{{ define "_partials/clean-object" }}
     {{ return (dict "title" .title "properties" .properties "additionalProperties" .additionalProperties "patternProperties" .patternProperties "required" .required "enum" .enum "anchor" .anchor) }}
 {{ end }}

layouts/_partials/navbar.html

@@ -80,7 +80,7 @@
 </div>
 </nav>
 
-{{ define "partials/version-string" }}
+{{ define "_partials/version-string" }}
     {{ $ret := "unstable version"}}
 
     {{ $status := .Site.Params.version.status }}

layouts/_partials/openapi/render-object-table.html

@@ -47,8 +47,8 @@
 
  <tr>
   <td><code>{{ $property_name }}</code></td>
-  <td><code>{{ partial "partials/property-type" $property | safeHTML }}</code></td>
+  <td><code>{{ partial "property-type" $property | safeHTML }}</code></td>
-  <td>{{ partial "partials/property-description" (dict "property" $property "required" $required) }}</td>
+  <td>{{ partial "property-description" (dict "property" $property "required" $required) }}</td>
  </tr>
 
     {{ end }}
@@ -71,8 +71,8 @@
 
  <tr>
   <td>&lt;Other properties&gt;</td>
-  <td><code>{{ partial "partials/property-type" .additionalProperties | safeHTML }}</code></td>
+  <td><code>{{ partial "property-type" .additionalProperties | safeHTML }}</code></td>
-  <td>{{ partial "partials/property-description" (dict "property" .additionalProperties) }}</td>
+  <td>{{ partial "property-description" (dict "property" .additionalProperties) }}</td>
  </tr>
     {{ end }}
 </table>
@@ -101,8 +101,8 @@ resolve-additional-types.)
  {{ $property := . }}
 
  <tr>
-  <td><code>{{ partial "partials/property-type" $property | safeHTML }}</code></td>
+  <td><code>{{ partial "property-type" $property | safeHTML }}</code></td>
-  <td>{{ partial "partials/property-description" (dict "property" $property) }}</td>
+  <td>{{ partial "property-description" (dict "property" $property) }}</td>
  </tr>
 </table>
 
@@ -138,7 +138,7 @@ resolve-additional-types.)
     * `format`: optional string for the format of the type, used for strings.
 
 */}}
-{{ define "partials/property-type" }}
+{{ define "_partials/property-type" }}
     {{ $type := "" }}
 
     {{ if eq .type "object" }}
@@ -215,7 +215,7 @@ resolve-additional-types.)
 
     * `anchor`: optional HTML element id for the target type, which will be used to link to it.
 */}}
-{{ define "partials/object-type-or-title" }}
+{{ define "_partials/object-type-or-title" }}
     {{ $type := "object" }}
     {{ if .properties }}
         {{/*
@@ -306,7 +306,7 @@ resolve-additional-types.)
       * `x-changedInMatrixVersion`: optional string indicating in which Matrix
         spec version this property was last changed.
 */}}
-{{ define "partials/property-description" -}}
+{{ define "_partials/property-description" -}}
     {{ $description := .property.description -}}
     {{ if .required -}}
         {{/*
@@ -331,7 +331,7 @@ resolve-additional-types.)
     Computes the type to display for a string format, given the identifier of
     the format as a string.
 */}} 
-{{ define "partials/string-format" }}
+{{ define "_partials/string-format" }}
   {{ $stringFormat := "" }}
 
   {{ with index site.Data "string-formats" . }}

layouts/_partials/openapi/render-operation.html

@@ -37,7 +37,7 @@
   <h1 id="{{ $anchor }}">
    <span class="http-api-method">{{ $method }}</span>
    <span class="endpoint{{ if $operation_data.deprecated }} deprecated-inline{{ end }}">{{ $endpoint }}</span>
-   {{ template "_default/_markup/td-heading-self-link.html" $anchor }}
+   {{ partial "td/heading-self-link.html" (dict "Anchor" $anchor) }}
   </h1>
 </summary>