clarification: Correct wording in appservice docs (#2330)

Co-authored-by: Denis Kasak <dkasak@termina.org.uk>

.github/ISSUE_TEMPLATE/release.md

@@ -1,6 +1,6 @@
 ---
-name: [SCT] Release checklist
-about: Used by the Spec Core Team to create a new release.
+name: '[SCT] Release checklist'
+about: 'Used by the Spec Core Team to create a new release.'
 title: 'Matrix 1.X'
 labels: 'release-blocker'
 assignees: ''
@@ -16,20 +16,22 @@ Previous release: <!-- LINK TO LAST RELEASE'S CHECKLIST -->
 
 Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
 
+* [ ] Pin this issue to the repo.
 * [ ] Ensure the social media account holders are available for the release day.
-* [ ] Blog post written
-* [ ] Check for release blockers that may have been missed
-* [ ] Review/fix the changelog
+* [ ] Blog post written.
+* [ ] Check for release blockers that may have been missed.
+* [ ] Review/fix the changelog.
 
 Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
-* [ ] Branch stuffs
-* [ ] Github release artifact
-* [ ] Published to spec.matrix.org
-* [ ] All links work
-* [ ] Publish blog post
-* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted
-* [ ] Post to Twitter/Mastodon
-* [ ] Close this issue
+* [ ] Branch stuffs.
+* [ ] Github release artifact.
+* [ ] Published to spec.matrix.org.
+* [ ] All links work.
+* [ ] Publish blog post.
+* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted.
+* [ ] Post to Twitter/Mastodon.
+* [ ] Close this issue.
+* [ ] Unpin this issue from the repo.
 
 Known release blockers:
 * [ ] <!-- Issue/PR link -->

.github/_typos.toml

@@ -10,3 +10,4 @@ au1ba7o = "au1ba7o"
 [default.extend-words]
 Appy = "Appy"
 fo = "fo"
+Iy = "Iy"

.github/pull_request_template.md

@@ -1,11 +1,3 @@
----
-name: Spec clarification/not a proposal
-about: A change that's not a spec proposal, such as a clarification to the spec itself.
-title: ''
-labels: ''
-assignees: ''
-
----
 
 ### Pull Request Checklist
 

.github/workflows/main.yml

@@ -1,4 +1,10 @@
 name: "Spec"
+
+env:
+  HUGO_VERSION: 0.153.3
+  PYTHON_VERSION: 3.13
+  NODE_VERSION: 24
+
 on:
   push:
     branches:
@@ -20,9 +26,9 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: ${{ env.NODE_VERSION }}
       - name: "🔎 Run validator"
         run: |
           npx @redocly/cli@latest lint data/api/*/*.yaml
@@ -34,9 +40,9 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -51,11 +57,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -70,11 +76,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -99,11 +105,11 @@ jobs:
         # the asterisk matching behaviour, not the literal string.
         run: |
           if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
-              echo ::set-output name=baseURL::/
+              echo "baseURL=/" >> "$GITHUB_OUTPUT"
           elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
+              echo "baseURL=/${GITHUB_REF/refs\/tags\//}" >> "$GITHUB_OUTPUT"
           else
-              echo ::set-output name=baseURL::/unstable
+              echo "baseURL=/unstable" >> "$GITHUB_OUTPUT"
           fi
 
   build-openapi:
@@ -114,9 +120,9 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -150,9 +156,14 @@ jobs:
               --api server-server \
               -r "$RELEASE" \
               -o spec/server-server-api/api.json
+          scripts/dump-openapi.py \
+              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
+              --api identity \
+              -r "$RELEASE" \
+              -o spec/identity-service-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: openapi-artifact
           path: openapi.tar.gz
@@ -166,16 +177,18 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
       - name: "➕ Install towncrier"
         run: "pip install 'towncrier'"
       - name: "Generate changelog"
         run: ./scripts/generate-changelog.sh vUNSTABLE
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: changelog-artifact
-          path: content/changelog/vUNSTABLE.md
+          path: content/changelog/unstable.md
 
   build-spec:
     name: "📖 Build the spec"
@@ -183,15 +196,17 @@ jobs:
     needs: [calculate-baseurl, build-openapi, generate-changelog]
     # run even if generate-changelog was skipped
     if: ${{ always() }}
+    env:
+      baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: ${{ env.NODE_VERSION }}
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.113.0'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
@@ -201,28 +216,33 @@ jobs:
           npm run get-proposals
       - name: "📥 Download generated changelog"
         if: "needs.generate-changelog.result == 'success'"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: changelog-artifact
           path: content/changelog
+
       - name: "⚙️ hugo"
-        run: hugo --baseURL "${{ needs.calculate-baseurl.outputs.baseURL }}" -d "spec"
+        run: hugo --baseURL "${baseURL}" -d "spec${baseURL}"
+
       # We manually unpack the spec OpenAPI definition JSON to the website tree
       # to make it available to the world in a canonical place:
       # https://spec.matrix.org/latest/client-server-api/api.json
       # Works for /unstable/ and /v1.1/ as well.
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
         run: |
-          tar -xzf openapi.tar.gz
+          tar -C "spec${baseURL}" --strip-components=1 -xzf openapi.tar.gz
 
       - name: "📦 Tarball creation"
-        run: tar -czf spec.tar.gz spec
+        run: |
+          cd spec
+          tar -czf ../spec.tar.gz *
+
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: spec-artifact
           path: spec.tar.gz
@@ -231,44 +251,49 @@ jobs:
     name: "🔎 Validate generated HTML"
     runs-on: ubuntu-latest
     needs: [calculate-baseurl, build-spec]
+    # Run even if `generate-changelog` was skipped.
+    #
+    # `build-spec` has a dependency on `generate-changelog` to ensure order of execution
+    # and to access `needs.generate-changelog.result`. However, `generate-changelog` is
+    # skipped on tag builds; even a transient dependency on `generate-changelog` is then
+    # enough for this step to also be skipped by default on tag builds. Hence the need for
+    # this explicit `if`.
+    if: ${{ !failure() && !cancelled() }}
     steps:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
 
       - name: "📥 Fetch built spec"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: spec-artifact
 
       - name: "📝 Unpack the spec"
-        # we have to unpack it into the right path given the baseurl, so that the
-        # links are correct.
-        # eg if baseurl is `/unstable`, we want to put the site in `spec/unstable`.
         run: |
-          mkdir -p "spec${baseURL}"
-          tar -C "spec${baseURL}" --strip-components=1 -xvzf spec.tar.gz
-        env:
-          baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
+          mkdir spec
+          tar -C spec -xvzf spec.tar.gz
 
       - name: "Run htmltest"
         uses: wjdp/htmltest-action@master
         with:
-          config: .htmltest.yaml
+          config: .htmltest.yml
 
   build-historical-spec:
     name: "📖 Build the historical backup spec"
     runs-on: ubuntu-latest
-    needs: [build-openapi]
+    needs: [calculate-baseurl, build-openapi]
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
+    env:
+      baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: ${{ env.NODE_VERSION }}
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.113.0'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
@@ -277,23 +302,62 @@ jobs:
           npm i
           npm run get-proposals
       - name: "⚙️ hugo"
-        # Create a baseURL like `/v1.2` out of the `v1.2` tag
+        env:
+          HUGO_PARAMS_VERSION_STATUS: "historical"
         run: |
-          echo -e '[params.version]\nstatus="historical"' > historical.toml
-          hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
+          hugo --baseURL "${baseURL}" -d "spec${baseURL}"
 
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
         run: |
-          tar -xzf openapi.tar.gz
+          tar -C "spec${baseURL}" --strip-components=1 -xzf openapi.tar.gz
 
       - name: "📦 Tarball creation"
-        run: tar -czf spec-historical.tar.gz spec
+        run: |
+          cd spec
+          tar -czf ../spec-historical.tar.gz *
+
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: spec-historical-artifact
           path: spec-historical.tar.gz
+
+  # If we're building a tag, create a release and publish the artifacts
+  create_release:
+    name: "Create release"
+    if: ${{ !failure() && !cancelled() && startsWith(github.ref, 'refs/tags/') }}
+    needs:
+      - build-spec
+      - build-historical-spec
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Check out changelogs"
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+        with:
+          sparse-checkout: |
+            content/changelog
+      - name: "📥 Download built spec"
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: spec-artifact
+      - name: "📥 Download historical spec artifact"
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: spec-historical-artifact
+      - name: "✨ Create draft release"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Remove front-matter from changelog
+          sed '1,/^---$/d' "content/changelog/${{ github.ref_name }}.md" > changelog.md
+
+          # Create a draft release, using the changelog as release notes, and attaching the spec artifacts.
+          gh release create -d -t "${{ github.ref_name }}" \
+            -F "changelog.md" \
+            "${{ github.ref_name }}" \
+            spec.tar.gz \
+            spec-historical.tar.gz

.github/workflows/netlify.yaml

@@ -25,29 +25,33 @@ jobs:
         id: readctx
         # we need to find the PR number that corresponds to the branch, which we do by
         # searching the GH API
+        env:
+          OWNER_LOGIN: ${{ github.event.workflow_run.head_repository.owner.login }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
         run: |
-          head_branch='${{github.event.workflow_run.head_repository.owner.login}}:${{github.event.workflow_run.head_branch}}'
+          head_branch="${OWNER_LOGIN}:${HEAD_BRANCH}"
           echo "head branch: $head_branch"
           pulls_uri="https://api.github.com/repos/${{ github.repository }}/pulls?head=$(jq -Rr '@uri' <<<$head_branch)"
           pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" |
                jq -r '.[] | .number')
           echo "PR number: $pr_number"
-          echo "::set-output name=prnumber::$pr_number"
+          echo "prnumber=$pr_number" >> "$GITHUB_OUTPUT"
         
       - name: '📥 Download artifact'
-        uses: dawidd6/action-download-artifact@268677152d06ba59fcec7a7f0b5d961b6ccd7e1e # v2.28.0
+        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
         with:
           workflow: main.yaml
           run_id: ${{ github.event.workflow_run.id }}
           name: spec-artifact
 
       - name: "📦 Extract Artifacts"
-        run: tar -xzvf spec.tar.gz && rm spec.tar.gz
+        run: |
+          mkdir spec
+          tar -C spec -xzvf spec.tar.gz && rm spec.tar.gz
         
       - name: "📤 Deploy to Netlify"
         id: netlify
-        # v2.1.0
-        uses: nwtgck/actions-netlify@7a92f00dde8c92a5a9e8385ec2919775f7647352
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
         with:
           publish-dir: spec
           deploy-message: "Deploy from GitHub Actions"

.github/workflows/release.yaml

@@ -12,30 +12,32 @@ jobs:
     defaults:
       run:
         working-directory: packages/npm
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - name: 🧮 Checkout code
         uses: actions/checkout@v4
 
       - name: 🔧 Yarn cache
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           cache: "yarn"
           cache-dependency-path: packages/npm/yarn.lock
           registry-url: "https://registry.npmjs.org"
 
+      # Ensure npm 11.5.1 or later is installed
+      - name: Update npm
+        run: npm install -g npm@latest
+
       - name: 🔨 Install dependencies
         run: "yarn install --frozen-lockfile"
 
+      # We bump the package.json version to git, we just need it for publish to do the right thing
       - name: 🎖 Bump package.json version
-        run: "yarn version --new-version $VERSION"
+        run: "yarn version --new-version ${VERSION#v} --no-git-tag-version"
         env:
           VERSION: ${{ github.event.release.tag_name }}.0
 
       - name: 🚀 Publish to npm
-        id: npm-publish
-        uses: JS-DevTools/npm-publish@5a85faf05d2ade2d5b6682bfe5359915d5159c6c # v2.2.1
-        with:
-          token: ${{ secrets.NPM_TOKEN }}
-          package: packages/npm
-          access: public
-          ignore-scripts: false
+        run: npm publish --provenance --access public --tag latest

.github/workflows/spell-check.yaml

@@ -14,6 +14,6 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Check spelling of proposals
-      uses: crate-ci/typos@ff3f309513469397e1094520fb7a054e057589e1
+      uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10
       with:
         config: ${{github.workspace}}/.github/_typos.toml

.gitignore

@@ -14,3 +14,4 @@ _rendered.rst
 /spec/
 changelogs/rendered.*
 .hugo_build.lock
+hugo_stats.json

.htmltest.yml

@@ -4,3 +4,4 @@
 IgnoreDirectoryMissingTrailingSlash: true
 DirectoryPath: spec
 CheckExternal: false
+IgnoreInternalEmptyHash: true

CONTRIBUTING.rst

@@ -12,7 +12,7 @@ The documentation style is described at
 https://github.com/matrix-org/matrix-spec/blob/main/meta/documentation_style.rst.
 
 Matrix-spec workflows
---------------------
+---------------------
 
 Specification changes
 ~~~~~~~~~~~~~~~~~~~~~
@@ -99,6 +99,8 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 * ``deprecation`` - Used when deprecating something.
 
+* ``removal`` - Used when removing something that was unused or previously deprecated.
+
 All news fragments must have a brief summary explaining the change in the
 contents of the file. The summary must end in a full stop to be in line with
 the style guide and formatting must be done using Markdown.
@@ -117,7 +119,7 @@ license - in our case, this is Apache Software License v2 (see LICENSE).
 In order to have a concrete record that your contribution is intentional
 and you agree to license it under the same terms as the project's license, we've adopted the
 same lightweight approach used by the `Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_,
-`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md`_, and many other
+`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md>`_, and many other
 projects: the `Developer Certificate of Origin <http://developercertificate.org/>`_
 (DCO). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix::
@@ -163,19 +165,6 @@ include the line in your commit or pull request comment::
 
     Signed-off-by: Your Name <your@email.example.org>
 
-...using your real name; unfortunately pseudonyms and anonymous contributions
-can't be accepted. Git makes this trivial - just use the -s flag when you do
-``git commit``, having first set ``user.name`` and ``user.email`` git configs
-(which you should have done anyway :)
-
-Private sign off
-~~~~~~~~~~~~~~~~
-
-If you would like to provide your legal name privately to the Matrix.org
-Foundation (instead of in a public commit or comment), you can do so by emailing
-your legal name and a link to the pull request to dco@matrix.org. It helps to
-include "sign off" or similar in the subject line. You will then be instructed
-further.
-
-Once private sign off is complete, doing so for future contributions will not
-be required.
+Git allows you to add this signoff automatically when using the ``-s``
+flag to ``git commit``, which uses the name and email set in your
+``user.name`` and ``user.email`` git configs.

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.110.0 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

assets/css/fonts/Inter.css

@@ -0,0 +1,63 @@
+/* cyrillic-ext */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-cyrillic-ext-normal.woff2) format('woff2');
+  unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
+}
+/* cyrillic */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-cyrillic-normal.woff2) format('woff2');
+  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+}
+/* greek-ext */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-greek-ext-normal.woff2) format('woff2');
+  unicode-range: U+1F00-1FFF;
+}
+/* greek */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-greek-normal.woff2) format('woff2');
+  unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;
+}
+/* vietnamese */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-vietnamese-normal.woff2) format('woff2');
+  unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;
+}
+/* latin-ext */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-latin-ext-normal.woff2) format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+/* latin */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-latin-normal.woff2) format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}

assets/css/fonts/README.md

@@ -3,7 +3,7 @@
 ## Inter.css
 
 `Inter.css` is a local copy of
-https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i, modified to pull
+https://fonts.googleapis.com/css2?family=Inter:opsz,wght@14..32,100..900&display=swap, modified to pull
 font files (`.woff2`) from local sources. It was created
 using `download_google_fonts_css.py`.
   
@@ -15,8 +15,8 @@ load them. Example call:
 
 ```sh
 python3 download_google_fonts_css.py \
-  "https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i" \
-  ../../fonts \
+  "https://fonts.googleapis.com/css2?family=Inter:opsz,wght@14..32,100..900&display=swap" \
+  ../../../static/fonts \
   ../../fonts
 ```
   

assets/css/fonts/download_google_fonts_css.py

@@ -84,7 +84,6 @@ new_css_file_lines = []
 font_lang = None
 font_family = None
 font_style = None
-font_weight = 0
 for line in original_contents:
     # Check if this line contains a font URL
     match = re.match(r".*url\((.*)\) format.*", line)
@@ -96,16 +95,17 @@ for line in original_contents:
         resp = requests.get(font_url)
         if resp.status_code == 200:
             # Save the font file
-            filename = "%s-%s-%s-%d.woff2" % (
-                font_family, font_lang, font_style, font_weight
+            filename = "%s-%s-%s.woff2" % (
+                font_family, font_lang, font_style
             )
             font_filepath = font_output_dir + filename
             with open(font_filepath, "wb") as f:
                 print("Writing font file:", font_filepath)
                 f.write(resp.content)
 
-            # Replace google URL with local URL
-            line = re.sub(r"url\(.+\)", f"url({css_font_path + filename})", line)
+            # Replace google URL with local URL and allow the browser to load the
+            # local font if it exists.
+            line = re.sub(r"url\(.+?\)", f"local('{font_family}'), url({css_font_path + filename})", line)
         else:
             print("Warning: failed to download font file:", font_url)
 
@@ -121,9 +121,6 @@ for line in original_contents:
     font_style_match = re.match(r".*font-style: (.+);$", line)
     if font_style_match:
         font_style = font_style_match.group(1)
-    font_weight_match = re.match(r".*font-weight: (.+);$", line)
-    if font_weight_match:
-        font_weight = int(font_weight_match.group(1))
 
     # Append the potentially modified line to the new css file
     new_css_file_lines.append(line)

assets/diagrams/README.md

@@ -7,11 +7,17 @@ https://www.diagrams.net/ is a great ([open source](https://github.com/jgraph/dr
 tool for these sorts of things - include your `.drawio` file next to your diagram.
 
 Suggested settings for diagrams.net:
-* Export as PNG.
-* 100% size.
+* Export as WebP.
+* 200% size.
 * `20` for a border width.
-* No transparent background, shadow, or grid.
-* Include a copy of the diagram.
+* Light appearance.
+* No shadow, or grid.
 
-To reference a diagram, use the absolute path when compiled. For example,
-`![membership-flow-diagram](/diagrams/membership.png)`
+To reference a diagram, use the `diagram` shortcode. For example:
+
+```
+{{% diagram name="membership" alt="Diagram presenting the possible membership state transitions" %}}
+```
+
+Where `name` is the file name without extension, and `alt` is a textual
+replacement for the image, useful for accessibility.

assets/icons/favicon.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
+   <style>
+      path { fill: #000000; }
+      @media (prefers-color-scheme: dark) {
+          path { fill: #ffffff; }
+      }
+   </style>
+   <path d="M 30,2.0000001 V 30 h -1 -2 v 2 h 5 V -3.3333334e-8 L 27,0 v 2 z"/>
+   <path d="M 9.9515939,10.594002 V 12.138 h 0.043994 c 0.3845141,-0.563728 0.8932271,-1.031728 1.4869981,-1.368 0.580003,-0.322998 1.244999,-0.485 1.993002,-0.485 0.72,0 1.376999,0.139993 1.971998,0.42 0.595,0.279004 1.047001,0.771001 1.355002,1.477001 0.338003,-0.500001 0.795999,-0.941 1.376999,-1.323001 0.579999,-0.382998 1.265998,-0.574 2.059998,-0.574 0.602003,0 1.160002,0.074 1.674002,0.220006 0.514,0.148006 0.953998,0.382998 1.321999,0.706998 0.36601,0.322999 0.653001,0.746 0.859,1.268002 0.205001,0.521998 0.307994,1.15 0.307994,1.887001 v 7.632997 h -3.127 v -6.463997 c 0,-0.383002 -0.01512,-0.743002 -0.04399,-1.082003 -0.02079,-0.3072 -0.103219,-0.607113 -0.242003,-0.881998 -0.133153,-0.25081 -0.335962,-0.457777 -0.584001,-0.596002 -0.257008,-0.146003 -0.605998,-0.220006 -1.046997,-0.220006 -0.440002,0 -0.796003,0.085 -1.068,0.253002 -0.272013,0.170003 -0.485001,0.390002 -0.639001,0.662003 -0.159119,0.287282 -0.263585,0.601602 -0.307994,0.926997 -0.05197,0.346923 -0.07801,0.697217 -0.07801,1.048002 v 6.353999 h -3.128005 v -6.398 c 0,-0.338003 -0.0072,-0.673001 -0.02116,-1.004001 -0.01134,-0.313663 -0.07487,-0.623229 -0.187994,-0.915999 -0.107943,-0.276623 -0.300435,-0.512126 -0.550001,-0.673001 -0.25799,-0.168 -0.636,-0.253002 -1.134999,-0.253002 -0.198123,0.0083 -0.394383,0.04195 -0.584002,0.100006 -0.258368,0.07446 -0.498455,0.201827 -0.704999,0.373985 -0.227981,0.183987 -0.421999,0.449 -0.583997,0.794003 -0.161008,0.345978 -0.242003,0.797998 -0.242003,1.356998 v 6.618999 H 6.99942 V 10.590001 Z"/>
+   <path d="M 2,2.0000001 V 30 h 3 v 2 H 0 V 9.2650922e-8 L 5,0 v 2 z"/>
+</svg>

assets/js/toc.js

@@ -0,0 +1,169 @@
+/*
+Copyright 2020, 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/*
+  Only call the given function once every 250 milliseconds to avoid impacting
+  the performance of the browser.
+  Source: https://remysharp.com/2010/07/21/throttling-function-calls
+*/
+function throttle(fn) {
+  const threshold = 250;
+  let last = null;
+  let deferTimer = null;
+
+  return function (...args) {
+    const now = new Date();
+
+    if (last && now < last + threshold) {
+      // Hold on to it.
+      clearTimeout(deferTimer);
+      deferTimer = setTimeout(() => {
+        last = now;
+        fn.apply(this, args);
+      }, threshold);
+    } else {
+      last = now;
+      fn.apply(this, args);
+    }
+  }
+}
+
+/*
+  Get the list of headings that appear in the ToC.
+  This is not as simple as querying all the headings in the content, because
+  some headings are not rendered in the ToC (e.g. in the endpoint definitions).
+*/
+function getHeadings() {
+  let headings = [];
+
+  // First get the anchors in the ToC.
+  const toc_anchors = document.querySelectorAll("#TableOfContents a");
+
+  for (const anchor of toc_anchors) {
+    // Then get the heading from its selector in the anchor's href.
+    const selector = anchor.getAttribute("href");
+    if (!selector) {
+      console.error("Got ToC anchor without href");
+      continue;
+    }
+
+    const heading = document.querySelector(selector);
+    if (!heading) {
+      console.error("Heading not found for selector:", selector);
+      continue;
+    }
+
+    headings.push(heading);
+  }
+
+  return headings;
+}
+
+/*
+  Get the heading of the text visible at the top of the viewport.
+  This is the first heading above or at the top of the viewport.
+*/
+function getCurrentHeading(headings, headerOffset) {
+  const scrollTop = document.documentElement.scrollTop;
+  let prevHeading = null;
+  let currentHeading = null;
+  let index = 0;
+
+  for (const heading of headings) {
+    // Compute the position compared to the viewport.
+    const rect = heading.getBoundingClientRect();
+
+    if (rect.top >= headerOffset && rect.top <= headerOffset + 30) {
+      // This heading is at the top of the viewport, this is the current heading.
+      currentHeading = heading;
+      break;
+    }
+    if (rect.top >= headerOffset) {
+      // This is in or below the viewport, the current heading should be the
+      // previous one.
+      if (prevHeading) {
+        currentHeading = prevHeading;
+      } else {
+        // The first heading does not have a prevHeading.
+        currentHeading = heading;
+      }
+      break;
+    }
+
+    prevHeading = heading;
+    index += 1;
+  }
+
+  // At the bottom of the page we might not have a heading.
+  if (!currentHeading) {
+    currentHeading = prevHeading;
+  }
+
+  return currentHeading;
+}
+
+/*
+  Select the ToC entry that points to the given ID.
+  Clear any previously highlighted ToC items, select the new one,
+  and adjust the ToC scroll position.
+*/
+function selectTocEntry(id) {
+  // Deselect previously selected entries.
+  const activeEntries = document.querySelectorAll("#TableOfContents a.active");
+  for (const activeEntry of activeEntries) {
+    activeEntry.classList.remove('active');
+  }
+
+  // Find the new entry and select it.
+  const newEntry = document.querySelector(`#TableOfContents a[href="#${id}"]`);
+  if (!newEntry) {
+    console.error("ToC entry not found for ID:", id);
+    return;
+  }
+  newEntry.classList.add('active');
+
+  // Don't scroll the sidebar nav if the main content is not scrolled
+  const nav = document.querySelector("#td-section-nav");
+  const content = document.querySelector("html");
+  if (content.scrollTop !== 0) {
+    nav.scrollTop = newEntry.offsetTop - 100;
+  } else {
+    nav.scrollTop = 0;
+  }
+}
+
+/*
+  Track when the view is scrolled, and use this to update the highlight for the
+  corresponding ToC entry.
+*/
+window.addEventListener('DOMContentLoaded', () => {
+  // Part of the viewport is below the header so we should take it into account.
+  const headerOffset = document.querySelector("body > header > nav").clientHeight;
+  const headings = getHeadings();
+
+  const onScroll = throttle((_e) => {
+    // Update the ToC.
+    let heading = getCurrentHeading(headings, headerOffset);
+    selectTocEntry(heading.id);
+  });
+
+  // Initialize the state of the ToC.
+  onScroll();
+
+  // Listen to scroll and resizing changes.
+  document.addEventListener('scroll', onScroll, false);
+  document.addEventListener('resize', onScroll, false);
+});

assets/js/versions.template.js

@@ -0,0 +1,114 @@
+/*
+Copyright 2025 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Determine the current version as defined in hugo.toml. This will either be
+// "unstable" or "vX.X" and doesn't depend on the current URL.
+//
+// The oddity below is an attempt at producing a readable Hugo template while
+// avoiding JS syntax errors in your IDE.
+const currentVersion = `{{ if eq .Site.Params.version.status "unstable" }}
+    {{- /**/ -}}
+    unstable
+    {{- /**/ -}}
+{{ else }}
+    {{- /**/ -}}
+    {{ printf "v%s.%s" .Site.Params.version.major .Site.Params.version.minor }}
+    {{- /**/ -}}
+{{ end }}`;
+
+// Determine the current version segment by regex matching the URL. This will either
+// be "unstable", "latest", "vX.X" (production) or undefined (local & netlify).
+const href = window.location.href;
+const segmentMatches = href.match(/(?<=\/)unstable|latest|v\d+.\d+(?=\/)/);
+const currentSegment = segmentMatches ? segmentMatches[0] : undefined;
+
+// Determine the selected menu element. If we were able to obtain the version
+// segment from the URL (production), use that. Otherwise (local & netlify),
+// fall back to the version as defined in Hugo.
+const selected = currentSegment ?? currentVersion;
+
+function appendVersion(parent, name, segment, url) {
+    // The list item
+    const li = document.createElement("li");
+    if (segment === selected) {
+        li.classList.add("version-picker-selected");
+    }
+    if (segment === "latest") {
+        li.classList.add("version-picker-latest");
+    }
+    parent.appendChild(li);
+
+    // The link
+    const a = document.createElement("a");
+    a.classList.add("dropdown-item");
+    a.setAttribute("href", url);
+    li.appendChild(a);
+
+    // Handle clicks manually to preserve the current path / fragment
+    a.addEventListener("click", (ev) => {
+        // If the URL is a relative link (i.e. the historical versions changelog), just
+        // let the browser load it
+        if (url.startsWith("/")) {
+            return;
+        }
+
+        // If we couldn't determine the current segment, we cannot safely replace
+        // it and have to let the browser load the (root) URL instead
+        if (!currentSegment) {
+            return;
+        }
+
+        // Otherwise, stop further event handling and replace the segment
+        ev.preventDefault();
+        ev.stopPropagation();
+        window.location.href = href.replace(`/${currentSegment}/`, `/${segment}/`);
+    });
+
+    // The link text
+    const text = document.createTextNode(name);
+    a.appendChild(text);
+}
+
+// If we're in the unstable version, we're the latest thing and can just load
+// versions.json from our own resources. Otherwise, we fall back to loading it
+// from /unstable/versions.json, assuming we are on the spec.matrix.org deployment.
+const url = currentVersion === "unstable"
+    ? '{{ .Site.Home.Permalink }}versions.json'
+    : "/unstable/versions.json";
+
+fetch(url)
+    .then(r => r.json())
+    .then(versions => {
+        // Find the surrounding list element
+        const ul = document.querySelector("ul#version-selector");
+        if (!ul) {
+            console.error("Cannot populate version selector: ul element not found");
+            return;
+        }
+
+        // Add a entries for the unstable version and the "latest" shortcut
+        appendVersion(ul, "unstable", "unstable", "https://spec.matrix.org/unstable");
+        const latestName = versions?.length ? `latest (${versions[0].name})` : "latest";
+        appendVersion(ul, latestName, "latest", "https://spec.matrix.org/latest");
+
+        // Add an entry for each proper version
+        for (const version of versions) {
+            appendVersion(ul, version.name, version.name, `https://spec.matrix.org/${version.name}`);
+        }
+
+        // For historical versions, simply link to the changelog
+        appendVersion(ul, "historical", "historical", '{{ (site.GetPage "changelog/historical").RelPermalink }}');
+    });

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);
@@ -40,10 +34,13 @@ Custom SCSS for the Matrix spec
   .navbar-brand {
     font-size: 1.1rem;
 
+    /* Allow the text to wrap if it is wider than the viewport */
+    text-align: center;
+    white-space: normal;
+
     .navbar-version {
       color: $secondary;
     }
-
   }
 
   .nav-link {
@@ -53,6 +50,20 @@ Custom SCSS for the Matrix spec
   a {
     color: $black;
   }
+
+  /* Make the version dropdown scroll if it's too large */
+  ul#version-selector {
+    max-height: 80vh;
+    overflow-y: auto;
+  }
+
+  ul#version-selector li.version-picker-selected a {
+    font-weight: bold;
+  }
+
+  ul#version-selector li.version-picker-latest a {
+    color: $secondary;
+  }
 }
 
 /* Styles for the sidebar nav */
@@ -67,9 +78,8 @@ Custom SCSS for the Matrix spec
 
   & > .td-sidebar-nav__section {
     margin-top: 1rem;
-  }
 
-  .td-sidebar-nav__section .ul-1 ul {
+    .ul-1 ul {
       padding-left: 0;
     }
 
@@ -86,8 +96,83 @@ Custom SCSS for the Matrix spec
     .ul-2 > li > a {
       padding-left: 2rem !important;
     }
+  }
 
-  a.td-sidebar-link.tree-root {
+  /* Styles for the table of contents */
+  & > .td-toc {
+    padding-top: 1rem;
+    padding-left: 1.5rem;
+    /* Add border above the toc */
+    border-top: 1px solid var(--bs-tertiary-color);
+
+    ol {
+      padding-left: 1rem;
+      counter-reset: section;
+      list-style-type: none;
+    }
+
+    #TableOfContents {
+      /* Remove the space between the title and the ToC */
+      margin-top: 0;
+
+      &>ol>li {
+        margin-bottom: .5rem;
+
+        &>a {
+          font-weight: $font-weight-bold;
+        }
+      }
+
+      ol {
+        padding-left: 0;
+      }
+
+      &>ol>li>a {
+        padding-left: 1rem;
+      }
+
+      &>ol>li>ol>li>a {
+        padding-left: 2rem;
+      }
+
+      &>ol>li>ol>li>ol>li>a {
+        padding-left: 3rem;
+      }
+
+      &>ol>li>ol>li>ol>li>ol>li>a {
+        padding-left: 4rem;
+      }
+
+      &>ol>li>ol>li>ol>li>ol>li>ol>li>a {
+        padding-left: 5rem;
+      }
+
+    }
+
+    li a:before {
+      counter-increment: section;
+      content: counters(section, ".") " ";
+    }
+
+    .td-toc-title {
+      font-weight: $font-weight-bold;
+      font-size: 1.3rem;
+
+      /* Remove the border under the title */
+      border-bottom: 0;
+      /* Remove the space under the title */
+      margin-bottom: 0;
+
+      /* Fix the top of page link color */
+      a, a:hover {
+        color: $secondary;
+      }
+    }
+  }
+
+  /* Apply the same style to links in the navigation and in the ToC */
+  & > .td-sidebar-nav__section, & > .td-toc #TableOfContents {
+    li a.td-sidebar-link.tree-root {
       color: $gray-800;
       font-weight: $font-weight-bold;
       font-size: 1.3rem;
@@ -95,13 +180,12 @@ Custom SCSS for the Matrix spec
       border-bottom: none;
     }
 
-  a, a.td-sidebar-link {
+    li a, li a.td-sidebar-link {
       color: $gray-800;
       font-weight: $font-weight-normal;
       padding-top: .2rem;
       padding-bottom: .2rem;
 
-    display: block;
       transition: all 100ms ease-in-out;
 
       &:hover {
@@ -114,8 +198,9 @@ Custom SCSS for the Matrix spec
       }
     }
   }
+}
 
-@media (min-width: 768px) {
+@include media-breakpoint-up(md) {
   @supports (position: sticky) {
     .td-sidebar-nav {
       /* This overrides calc(100vh - 10rem);, which gives us a blank space at the bottom of the sidebar */
@@ -125,8 +210,11 @@ Custom SCSS for the Matrix spec
 }
 
 /* Customise footer */
-footer {
+.td-footer {
   box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
+  padding-top: 2rem;
+  color: var(--bs-body-color);
+  background-color: var(--bs-body-color-bg);
 }
 
 /* Auto numbering for headings */
@@ -172,68 +260,80 @@ footer {
 
 }
 
+/* Remove some padding before the main content, when the sidebar is disabled */
+.td-main main {
+  @include media-breakpoint-down(md) {
+    padding-top: 0;
+  }
+}
+
 /* Adjust the scroll margin for everything in the main content, so that
  * it doesn't disappear behind the header bar */
 .td-content * {
   scroll-margin-top: 5.5rem;
 }
 
-/* Styles for the table of contents */
-#toc {
-  padding-top: .5rem;
-  padding-left: 1.5rem;
-
-  ol {
-    padding-left: 1rem;
-    counter-reset: section;
-    list-style-type: none;
-  }
-
-  #TableOfContents {
-    &>ol>li {
-      margin-bottom: .5rem;
-
-      &>a {
+.endpoints-toc {
+  summary {
+    cursor: pointer;
     font-weight: $font-weight-bold;
-      }
+    font-size: 1.05rem;
+    margin-bottom: 0.5rem;
   }
 
-    ol {
+  .endpoint-list {
+    list-style: none;
     padding-left: 0;
+    margin: 0;
   }
 
-    &>ol>li>a {
-      padding-left: 1rem;
+  .endpoint-list li {
+    margin: 0.2rem 0;
   }
 
-    &>ol>li>ol>li>a {
-      padding-left: 2rem;
+  .endpoint-list a {
+    text-decoration: none;
+    color: inherit;
+    padding: 0.05rem 0.25rem;
+    border-radius: 0.2rem;
+
+    &:hover {
+      background-color: $secondary-background;
+    }
   }
 
-    &>ol>li>ol>li>ol>li>a {
-      padding-left: 3rem;
-    }
-
-    &>ol>li>ol>li>ol>li>ol>li>a {
-      padding-left: 4rem;
-    }
-
-    &>ol>li>ol>li>ol>li>ol>li>ol>li>a {
-      padding-left: 5rem;
-    }
-
-  }
-
-  li a:before {
-    counter-increment: section;
-    content: counters(section, ".") " ";
-  }
-
-  #toc-title {
+  .endpoint-list .http-api-method {
+    margin-right: 0.35rem;
     font-weight: $font-weight-bold;
-    font-size: 1.3rem;
   }
 
+  .endpoint-path {
+    font-family: $font-family-monospace;
+    color: $secondary;
+  }
+
+  .endpoint-deprecated {
+    color: $danger;
+    font-weight: $font-weight-bold;
+    margin-left: 0.35rem;
+  }
+
+  .endpoint-module {
+    &:not(:first-child) {
+      margin-top: 0.75rem;
+    }
+  }
+
+  .endpoint-module-title {
+    // font-weight: $font-weight-bold;
+    font-size: 1.20rem;
+    margin-bottom: 0.35rem;
+  }
+}
+
+.page-description {
+  margin-bottom: 1rem;
+  color: inherit;
 }
 
 /* Styles for alert boxes */
@@ -267,29 +367,6 @@ footer {
     border-left-width: 5px;
     background: $warning-background;
   }
-
-  // XXX: See the added-in-paragraph.html shortcode for more information on these styles.
-  &.added-in-paragraph {
-    // Remove the padding and margin to remove the box look
-    margin: 0 !important; // !important on both to override table-related rules
-    padding: 0 !important;
-
-    // Make pairs of "added-in" and content inline to each other. We do pairs so authors can
-    // describe two paragraphs with added-in prefixes within a single box, reducing DOM
-    // complexity. Each paragraph is expected to be prefixed with an added-in, however.
-    //
-    // XXX: We assume the added-in and text will be rendered as paragraph elements.
-    > p {
-      display: inline;
-    }
-    > p:nth-child(2n) { // "even" rule to target just the content paragraphs
-      // Force a paragraph break after the content (insert a couple <br /> tags)
-      &::after {
-        content: '\A\A';
-        white-space: pre;
-      }
-    }
-  }
 }
 
 /* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
@@ -332,13 +409,19 @@ footer {
   h2 {
     font-weight: $font-weight-bold;
     font-size: 1.3rem;
-    margin: 3rem 0 .5rem 0;
+    margin: 1.5rem 0 1rem 0;
   }
 
   h3 {
     font-weight: $font-weight-bold;
     font-size: 1.1rem;
-    margin: 1.5rem 0 .75rem 0;
+    margin: 1.5rem 0 1rem 0;
+
+  }
+
+  /* Reduce top margin of h3 if previous sibling is a h2 */
+  h2 + h3 {
+    margin-top: 1rem;
   }
 
   hr {
@@ -383,11 +466,6 @@ footer {
       }
     }
 
-    // add some space between two tables when they are right next to each other
-    & + table {
-        margin-top: 4rem;
-    }
-
     caption {
       caption-side: top;
       color: $dark;
@@ -400,6 +478,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;
 
@@ -427,6 +510,42 @@ footer {
     &.basic-info th {
       width: 15rem;
     }
+
+    /* Arrange rows vertically when horizontal space is constrained to avoid overflowing */
+    @include media-breakpoint-down(sm) {
+      /* Make cells full width without vertical margin */
+      &.basic-info th, &.basic-info td {
+        width: 100%;
+        display: inline-block;
+        margin-top: 0;
+        margin-bottom: 0;
+      }
+
+      /* Remove border and padding between header & data cells to make them appear like a single cell */
+      &.basic-info td {
+        padding-top: 0;
+        border-top: none;
+      }
+      &.basic-info th {
+        border-bottom: none;
+      }
+
+      /* Remove top border on all but the first header cell to prevent double borders between rows */
+      &.basic-info tr + tr th {
+        border-top: none;
+      }
+    }
+  }
+
+  /* Have consistent spacing around tables and examples */
+  table, .highlight {
+    margin-top: 0;
+    margin-bottom: 2rem;
+
+    /* We don't need the margin on the last child of the .rendered-data block */
+    &:last-child {
+      margin-bottom: 0;
+    } 
   }
 
   pre {
@@ -471,12 +590,25 @@ of .td-content. This applies the same style to any blockquotes that descend from
 Make padding symmetrical (this selector is used in the default styles to apply padding-left: 3rem)
 */
 .pl-md-5, .px-md-5 {
+  @include media-breakpoint-up(md) {
     padding-right: 3rem;
   }
+}
+
+/* Adjust the width of math to match normal paragraphs */
+@include media-breakpoint-up(lg) {
+  .katex-display {
+    max-width: 80%;
+  }
+}
 
 /* Adjust default styles for info banner */
 .pageinfo-primary {
+  @include media-breakpoint-up(lg) {
     max-width: 80%;
+  }
+  margin-top: 0;
+  margin-right: 0;
   margin-left: 0;
   border: 0;
   border-left: solid 5px $secondary;

assets/scss/_variables_project.scss

@@ -18,6 +18,7 @@ $primary: #FFF;
 $secondary: #0098D4;
 $dark: #333;
 $gray-100: #FBFBFB;
+$code-color: #005b7f;
 
 $secondary-background: #E5F5FB;
 $secondary-lighter-background: #F4FAFC;
@@ -40,15 +41,17 @@ $table-bg: $secondary-lightest-background;
 $td-enable-google-fonts: false;
 
 /*
- * Replace the default font with Inter.
- *
- * The $font-family-sans-serif definition here overrides the default value set by docsy:
- * https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68
- * and adds "Inter" to the front.
- *
- * The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html.
+ * The $font-family-sans-serif definition here overrides the default value set by docsy
+ * (https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68)
  */
-$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+$font-family-sans-serif:
+  // Add "Inter" to the front, making it the default. The font itself is loaded via stylesheet
+  // links in layouts/partials/hooks/head-end.html.
+  "Inter",
+  -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
+  // Insert fonts suited for mathematical symbols on different platforms before "Arial"
+  "STIX Two Math", "Cambria Math", "Noto Sans Math", "Dejavu Sans",
+  Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
 
 // Disable smooth scrolling as it makes TOC highlighting jump during the transition.
 $enable-smooth-scroll: false;

changelogs/appendices/newsfragments/2307.clarification

@@ -0,0 +1 @@
+Add identifier pronunciation guidelines. Contributed by @HarHarLinks.

changelogs/application_service/newsfragments/2330.clarification

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

changelogs/client_server/newsfragments/2270.feature

@@ -0,0 +1 @@
+Add the account management capabilities for the OAuth 2.0 authentication API, as per [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191).

changelogs/client_server/newsfragments/2272.feature

@@ -0,0 +1 @@
+Add OAuth 2.0 aware clients, as per [MSC3824](https://github.com/matrix-org/matrix-spec-proposals/pull/3824).

changelogs/client_server/newsfragments/2277.clarification

@@ -0,0 +1,3 @@
+The optional `submit_url` response parameter of the `/requestToken` endpoints uses the same request
+and response parameters and error codes as the Identity Service API's `POST /_matrix/identity/v2/validate/email/submitToken`,
+as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183).

changelogs/client_server/newsfragments/2278.feature

@@ -0,0 +1 @@
+Add administrator endpoints to lock and suspend server-local users and add the `m.account_management` capability, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.1

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.2

@@ -0,0 +1 @@
+Add `PUT /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.3

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.4

@@ -0,0 +1 @@
+Add `PUT /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2280.clarification

@@ -0,0 +1 @@
+Update non-historic mentions of matrix-doc repo to matrix-spec/-proposals. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2283.clarification

@@ -0,0 +1 @@
+Remove unintended TeX formatting. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2291.feature

@@ -0,0 +1 @@
+Add `m.recent_emoji` account data event to track recently used emoji as per [MSC4356](https://github.com/matrix-org/matrix-spec-proposals/pull/4356).

changelogs/client_server/newsfragments/2292.feature

@@ -0,0 +1 @@
+Add `m.forget_forced_upon_leave` capability for servers to transparently auto-forget rooms that the user leaves as per [MSC4267](https://github.com/matrix-org/matrix-spec-proposals/pull/4267).

changelogs/client_server/newsfragments/2298.feature

@@ -0,0 +1 @@
+Add support for `m.room.redaction` events at the `PUT /rooms/{roomId}/send/{eventType}/{txnId}` endpoint, as per [MSC4169](https://github.com/matrix-org/matrix-spec-proposals/pull/4169).

changelogs/client_server/newsfragments/2299.feature

@@ -0,0 +1 @@
+Clients supporting the `ol` HTML element must also support the `start` attribute, as per [MSC4313](https://github.com/matrix-org/matrix-spec-proposals/pull/4313).

changelogs/client_server/newsfragments/2301.feature

@@ -0,0 +1 @@
+Add recommendation about excluding non-cross-signed devices from encrypted conversations, as per [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153).

changelogs/client_server/newsfragments/2304.clarification

@@ -0,0 +1 @@
+Clarify the requiredness of `event_id` in `predecessor`.

changelogs/client_server/newsfragments/2305.feature

@@ -0,0 +1 @@
+Add invite blocking, as per [MSC4380](https://github.com/matrix-org/matrix-spec-proposals/pull/4380).

changelogs/client_server/newsfragments/2306.clarification

@@ -0,0 +1 @@
+Clarify terminology for keys in cross-signing module.

changelogs/client_server/newsfragments/2311.feature

@@ -0,0 +1 @@
+`/_matrix/client/v3/rooms/{roomId}/report` and `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` may respond with HTTP 200 regardless of the reported subject's existence or add a random delay when generating responses as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277).

changelogs/client_server/newsfragments/2311.removal

@@ -0,0 +1 @@
+The `score` request parameter on `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` was removed as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277).

changelogs/client_server/newsfragments/2316.clarification

@@ -0,0 +1 @@
+Add 404 responses to the OpenAPI of `GET /login` and `GET /auth_metadata` endpoints. The responses were already defined in text but not written in OpenAPI.

changelogs/client_server/newsfragments/2318.clarification

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

changelogs/client_server/newsfragments/2324.clarification

@@ -0,0 +1 @@
+Clarified attachment encryption to require secure generation of keys and hash verification.

changelogs/header.md

@@ -1,16 +0,0 @@
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    VERSION  = Replaced by the version number (eg: v1.2)
-    DATE     = Replaced by the date (eg: April 01, 2021)
--->
-
-## VERSION
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/VERSION">https://github.com/matrix-org/matrix-spec/tree/VERSION</a></td>
-<tr><th>Release date</th><td>DATE</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

changelogs/identity_service/newsfragments/2277.clarification

@@ -0,0 +1,3 @@
+Clarify the error codes that can be returned with a 400 HTTP status code by the `POST /_matrix/identity/v2/validate/email/submitToken`
+and `POST /_matrix/identity/v2/validate/msisdn/submitToken` endpoints, introducing the `M_TOKEN_INCORRECT`
+error code, as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183).

changelogs/internal/newsfragments/2222.clarification

@@ -0,0 +1 @@
+Clarify vendor prefixing requirements.

changelogs/internal/newsfragments/2275.clarification

@@ -0,0 +1 @@
+Auto-create draft releases when building release tags.

changelogs/internal/newsfragments/2276.feature

@@ -0,0 +1 @@
+Include the spec release version in the filenames in the tarballs generated by CI.

changelogs/internal/newsfragments/2282.clarification

@@ -0,0 +1 @@
+Replace the Twitter link in the footer with our BlueSky and Mastodon socials.

changelogs/internal/newsfragments/2287.clarification

@@ -0,0 +1 @@
+Upgrade to docsy v0.13.0.

changelogs/internal/newsfragments/2289.clarification

@@ -0,0 +1 @@
+Updates to the release documentation.

changelogs/internal/newsfragments/2290.clarification

@@ -0,0 +1 @@
+Remove unused leftover CSS files.

changelogs/internal/newsfragments/2317.clarification

@@ -0,0 +1 @@
+Update the footer social links to match matrix.org. Contributed by @HarHarLinks.

changelogs/internal/newsfragments/2318.clarification

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

changelogs/internal/newsfragments/2323.clarification

@@ -0,0 +1 @@
+Render error code sections as definition lists to improve readability.

changelogs/room_versions/newsfragments/2297.clarification

@@ -0,0 +1 @@
+Clarify meaning of floating-point powerlevels.

changelogs/room_versions/newsfragments/2303.clarification

@@ -0,0 +1 @@
+Remove the post-1.16 release note for room version 12.

changelogs/server_server/newsfragments/2191.clarification

@@ -0,0 +1 @@
+Clarify what the `minimum_valid_until_ts` field means when it is set in key queries.

changelogs/server_server/newsfragments/2284.clarification

@@ -0,0 +1 @@
+Specify validation for PDUs passed to and returned from federation membership endpoints.

changelogs/server_server/newsfragments/2288.clarification

@@ -0,0 +1 @@
+Specify that callers of `/_matrix/federation/v1/openid/userinfo` must validate the returned user ID.

changelogs/server_server/newsfragments/2300.clarification

@@ -0,0 +1 @@
+Change `m.signing_update` typo to `m.signing_key_update`. Contributed by @velikopter

changelogs/server_server/newsfragments/2319.removal

@@ -0,0 +1 @@
+Remove `/v1/send_join` and `/v1/send_leave`, as per [MSC4376](https://github.com/matrix-org/matrix-spec-proposals/pull/4376).

changelogs/template.md.jinja

@@ -1,7 +1,7 @@
 {% for section_name, section in sections.items() %}
 {% if section_name %}
 
-### {{section_name}}
+## {{section_name}}
 {% endif %}
 
 {% if section %}

config/_default/hugo.toml

@@ -1,45 +1,57 @@
+# Default settings.
+
 baseURL = "/"
 title = "Matrix Specification"
 
-# Prepends absolute URLs with the baseURL. Useful when hosting on non-root
-# paths, such as /unstable.
-canonifyURLs = true
-
 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", "taxonomyTerm", "RSS"]
+disableKinds = ["taxonomy", "rss"]
 
 [languages]
 [languages.en]
 title = "Matrix Specification"
-description = "Home of the Matrix specification for decentralised communication"
 languageName ="English"
 # Weight used for sorting.
 weight = 1
+[languages.en.params]
+description = "Home of the Matrix specification for decentralised communication"
 
 # Entries in the main menu in the header.
 [menus]
 [[menus.main]]
     name = 'Foundation'
-    url = 'https://matrix.org/foundation/'
+    url = 'https://matrix.org/foundation/about/'
     weight = 10
 [[menus.main]]
-    name = 'FAQs'
-    url = 'https://matrix.org/faq'
+    name = 'User Docs'
+    url = 'https://matrix.org/docs/'
     weight = 20
 [[menus.main]]
     name = 'Blog'
-    url = 'https://matrix.org/blog/posts'
+    url = 'https://matrix.org/blog/'
     weight = 30
 
 [markup]
+  [markup.tableOfContents]
+    startLevel = 2
+    endLevel = 6
+    ordered = true
   [markup.goldmark]
     [markup.goldmark.renderer]
       # Enables us to render raw HTML
       unsafe = true
+    [markup.goldmark.extensions]
+      # Tell Goldmark to pass delimited blocks through the `render-passthrough` render hook.
+      # This is used to render the maths in the Olm spec.
+      # See: https://gohugo.io/functions/transform/tomath/#step-1.
+      [markup.goldmark.extensions.passthrough]
+        enable = true
+        [markup.goldmark.extensions.passthrough.delimiters]
+          block = [['\[', '\]']]
+          inline = [['\(', '\)']]
   [markup.highlight]
       # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
       # If the style is changed, remember to regenerate the CSS with:
@@ -53,25 +65,25 @@ weight = 1
 # Everything below this are Site Params
 
 [params]
-copyright = "The Matrix.org Foundation CIC"
-privacy_policy = "https://matrix.org/legal/privacy-notice"
+copyright = "The Matrix.org Foundation C.I.C."
 
 [params.version]
 # must be one of "unstable", "current", "historical"
 # this is used to decide whether to show a banner pointing to the current release
-status = "stable"
+status = "unstable"
 # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner.
 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. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created.
-major = "1"
-minor = "10"
-release_date = "March 22, 2024"
+# of the spec.
+#major = "1"
+#minor = "17"
+
+[[params.versions]]
+# We must include this parameter to enable docsy's version picker in the navbar. The picker
+# is populated automatically in navbar-version-selector.html.
 
 # User interface configuration
 [params.ui]
-# Set to true to disable the About link in the site footer
-footer_about_disable = false
 # Collapse HTTP API and event <details> elements
 rendered_data_collapsed = false
 # Hide the search entry in the sidebar
@@ -87,26 +99,47 @@ sidebar_menu_compact = true
 # 	icon = "fa fa-envelope"
 #         desc = "Discussion and help from your fellow users"
 # Developer relevant links. These will show up on right side of footer and in the community page if you have one.
-[[params.links.developer]]
+# [[params.links.developer]]
+# 	name = "GitHub"
+# 	url = "https://github.com/matrix-org"
+# 	icon = "fab fa-github"
+#   desc = "Matrix on GitHub"
+# Custom links shown in the center of the footer. (Only supported by our fork of docsy's 'footer/central' partial.)
+[[params.links.bottom]]
   name = "GitHub"
   url = "https://github.com/matrix-org"
   icon = "fab fa-github"
   desc = "Matrix on GitHub"
-[[params.links.developer]]
+[[params.links.bottom]]
   name = "GitLab"
   url = "https://gitlab.matrix.org/matrix-org"
   icon = "fab fa-gitlab"
   desc = "Matrix on GitLab"
-[[params.links.developer]]
+[[params.links.bottom]]
+  name = "Mastodon"
+  url = "https://mastodon.matrix.org/@matrix"
+  icon = "fab fa-mastodon"
+  desc = "Matrix on Mastodon"
+[[params.links.bottom]]
+  name = "Bluesky"
+  url = "https://bsky.app/profile/matrix.org"
+  icon = "fab fa-bluesky"
+  desc = "Matrix on Bluesky"
+[[params.links.bottom]]
+  name = "LinkedIn"
+  url = "https://www.linkedin.com/company/matrix-org/"
+  icon = "fab fa-linkedin"
+  desc = "Matrix on LinkedIn"
+[[params.links.bottom]]
   name = "YouTube"
   url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
   icon = "fab fa-youtube"
   desc = "Matrix YouTube channel"
-[[params.links.developer]]
-	name = "Twitter"
-	url = "https://twitter.com/matrixdotorg"
-	icon = "fab fa-twitter"
-  desc = "Matrix on Twitter"
+[[params.links.bottom]]
+  name = "Matrix.org Blog Feed"
+  url = "https://matrix.org/atom.xml"
+  icon = "fas fa-rss"
+  desc = "Matrix.org Blog Atom Feed"
 
 
 # configuration for the hugo development server
@@ -116,7 +149,9 @@ sidebar_menu_compact = true
 [[server.headers]]
   for = '/**'
   [server.headers.values]
-    Content-Security-Policy = "default-src 'self'; style-src 'self'; script-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; media-src 'self'; child-src 'self'; form-action 'self'; object-src 'self'"
+    # `style-src 'unsafe-inline'` is needed to correctly render the maths in the Olm spec:
+    # https://github.com/KaTeX/KaTeX/issues/4096
+    Content-Security-Policy = "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; media-src 'self'; child-src 'self'; form-action 'self'; object-src 'self'"
     X-XSS-Protection = "1; mode=block"
     X-Content-Type-Options = "nosniff"
     # Strict-Transport-Security = "max-age=31536000; includeSubDomains; preload"
@@ -129,7 +164,23 @@ sidebar_menu_compact = true
 [module]
   [module.hugoVersion]
     extended = true
-    min = "0.110.0"
+    min = "0.146.0"
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false
+
+# custom output formats
+
+[outputFormats]
+  [outputFormats.Checklist]
+    mediaType = "text/markdown"
+    isPlainText = true
+    baseName = "checklist"
+
+# Add font media types for downloading KaTeX fonts.
+# See: https://www.docsy.dev/docs/content/diagrams-and-formulae/#create-media-types-for-katex-fonts
+[mediaTypes]
+  [mediaTypes.'font/woff']
+    suffixes = ['woff']
+  [mediaTypes.'font/woff2']
+    suffixes = ['woff2']

config/production/hugo.toml

@@ -0,0 +1,6 @@
+# Settings only required when the website is built for production.
+
+# Enable stats to use them to optimize the CSS.
+[build]
+  [build.buildStats]
+    enable = true

content/_index.md

@@ -25,6 +25,7 @@ The specification consists of the following parts:
 * [Identity Service API](/identity-service-api)
 * [Push Gateway API](/push-gateway-api)
 * [Room Versions](/rooms)
+* [Olm & Megolm](/olm-megolm)
 * [Appendices](/appendices)
 
 Additionally, this introduction page contains the key baseline
@@ -56,9 +57,6 @@ The principles that Matrix attempts to follow are:
         the global Matrix network
     -   Fully open standard - publicly documented standard with no IP or
         patent licensing encumbrances
-    -   Fully open source reference implementation - liberally-licensed
-        example implementations with no IP or patent licensing
-        encumbrances
 -   Empowering the end-user
     -   The user should be able to choose the server and clients they
         use
@@ -99,6 +97,20 @@ services - be that for instant messages, VoIP call setups, or any other
 objects that need to be reliably and persistently pushed from A to B in
 an interoperable and federated manner.
 
+### Requirement levels
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" across all parts of the
+specification are to be interpreted as described in
+[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+Some entire sections of the specification might be optional depending on the
+circumstances. For example, the
+[modules of the client-server API](/client-server-api/#modules)
+apply depending on the use case. The requirement level expressed by the above
+key words appearing in such a section is only relevant if the section itself is
+applicable.
+
 ### Spec Change Proposals
 
 To propose a change to the Matrix Spec, see the explanations at
@@ -140,7 +152,7 @@ request.
 
 How data flows between clients:
 
-```
+```nohighlight
     { Matrix client A }                             { Matrix client B }
         ^          |                                    ^          |
         |  events  |  Client-Server API                 |  events  |
@@ -493,18 +505,23 @@ For historical reference, the APIs were versioned as `rX.Y.Z` where `X`
 roughly represents a breaking change, `Y` a backwards-compatible change, and
 `Z` a patch or insignificant alteration to the API.
 
-`v1.0` of Matrix was released on June 10th, 2019 with the following API
-versions:
+The current global versioning system was introduced with `v1.1`.
+[Matrix 1.0](https://matrix.org/blog/2019/06/11/introducing-matrix-1-0-and-the-matrix-org-foundation/)
+did not correspond directly to a specification version; instead, it was based on
+the following versions for the individual APIs:
 
 | API/Specification        | Version       |
-|-------------------------|---------|
+|--------------------------|---------------|
 | Client-Server API        | r0.5.0        |
 | Server-Server API        | r0.1.2        |
 | Application Service API  | r0.1.1        |
-| Identity Service API    | r0.1.1  |
+| Identity Service API     | r0.2.0        |
 | Push Gateway API         | r0.1.0        |
-| Room Version            | v5      |
+| Room Versions            | 1, 2, 3, 4, 5 |
 
+`v1.0` should **not** be returned by servers in the
+[`GET /_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
+response.
 
 ## License
 

content/appendices.md

@@ -533,6 +533,11 @@ where `domain` is the [server name](#server-name) of the homeserver
 which allocated the identifier, and `localpart` is an identifier
 allocated by that homeserver.
 
+Because the domain part identifies the server on which the ID resolves,
+the canonical pronunciation of the separating `:` is "on".
+For example, `@user:matrix.org` would be pronounced as "at user on matrix dot
+org".
+
 The precise grammar defining the allowable format of an identifier
 depends on the type of identifier. For example, event IDs can sometimes
 be represented with a `domain` component under some conditions - see the
@@ -556,7 +561,7 @@ The `domain` of a user ID is the [server name](#server-name) of the
 homeserver which allocated the account.
 
 The length of a user ID, including the `@` sigil and the domain, MUST
-NOT exceed 255 characters.
+NOT exceed 255 bytes.
 
 The complete grammar for a legal user ID is:
 
@@ -611,10 +616,18 @@ characters permitted in user ID localparts. There are currently active
 users whose user IDs do not conform to the permitted character set, and
 a number of rooms whose history includes events with a `sender` which
 does not conform. In order to handle these rooms successfully, clients
-and servers MUST accept user IDs with localparts from the expanded
-character set:
+and servers MUST accept user IDs with localparts consisting of any legal
+non-surrogate Unicode code points except for `:` and `NUL` (U+0000), including other control
+characters and the empty string.
 
-    extended_user_id_char = %x21-39 / %x3B-7E  ; all ASCII printing chars except :
+User IDs with localparts containing characters outside the range U+0021 to U+007E, or with
+an empty localpart, are considered non-compliant. For current room versions, servers must
+still accept events using such user IDs over federation; however they SHOULD NOT forward
+such user IDs to clients when referenced outside the context of an event. For example,
+device list updates from non-compliant user IDs would be dropped by the receiving server.
+
+A future room version may prevent users using a historical character set
+from participating. Use of the historical character set is *deprecated*.
 
 ##### Mapping from other character sets
 
@@ -649,19 +662,48 @@ provides no way to encode ASCII punctuation).
 
 #### Room IDs
 
-A room has exactly one room ID. A room ID has the format:
+{{% changed-in v="1.16" %}} Room IDs can now appear without a domain depending on
+the room version.
+
+A room has exactly one room ID. Room IDs take the form:
+
+    !opaque_id
+
+However, the precise format depends upon the [room version specification](/rooms):
+some room versions included a `domain` component, whereas more recent room versions
+omit the domain and use a base64-encoded hash instead.
+
+Room IDs are case-sensitive and not meant to be human-readable. They are intended
+to be used as fully opaque strings by clients, even when a `domain` component is
+present.
+
+If the room version requires a `domain` component, room IDs take the following
+form:
 
     !opaque_id:domain
 
-The `domain` of a room ID is the [server name](#server-name) of the
-homeserver which created the room. The domain is used only for
-namespacing to avoid the risk of clashes of identifiers between
-different homeservers. There is no implication that the room in
-question is still available at the corresponding homeserver.
+In such a form, the `opaque_id` is a localpart. The localpart MUST only contain
+valid non-surrogate Unicode code points, including control characters, except `:`
+and `NUL` (U+0000). The localpart SHOULD only consist of alphanumeric characters
+(`A-Z`, `a-z`, `0-9`) when generating them. The `domain` is the [server name](#server-name)
+of the homeserver which created the room - it is only used to reduce namespace
+collisions. There is no implication that the room in question is still available
+at the corresponding homeserver. Combined, the localpart, domain, and `!` sigil
+MUST NOT exceed 255 bytes.
 
-Room IDs are case-sensitive. They are not meant to be
-human-readable. They are intended to be treated as fully opaque strings
-by clients.
+When a room version requires the `domain`-less format, room IDs are simply the
+[event ID](#event-ids) of the `m.room.create` event using `!` as the sigil instead
+of `$`. The grammar is otherwise inherited verbatim.
+
+{{% boxes/note %}}
+Applications which previously relied upon the `domain` in a room ID can instead
+parse the [user IDs](#user-identifiers) found in the `m.room.create` event's `sender`.
+
+Though the `m.room.create` event's `additional_creators` (in `content`) may be
+used when present, applications should take care when parsing or interpreting the
+list. The user IDs in `additional_creators` will have correct grammar, but may
+not be real users or may not belong to actual Matrix homeservers.
+{{% /boxes/note %}}
 
 #### Room Aliases
 
@@ -673,8 +715,11 @@ The `domain` of a room alias is the [server name](#server-name) of the
 homeserver which created the alias. Other servers may contact this
 homeserver to look up the alias.
 
-Room aliases MUST NOT exceed 255 bytes (including the `#` sigil and the
-domain).
+The localpart of a room alias may contain any valid non-surrogate Unicode codepoints
+except `:` and `NUL`.
+
+The length of a room alias, including the `#` sigil and the domain, MUST
+NOT exceed 255 bytes.
 
 #### Event IDs
 
@@ -686,10 +731,12 @@ However, the precise format depends upon the [room version
 specification](/rooms): early room versions included a `domain` component,
 whereas more recent versions omit the domain and use a base64-encoded hash instead.
 
+In addition to the requirements of the room version, the length of an event ID,
+including the `$` sigil and the domain where present, MUST NOT exceed 255 bytes.
+
 Event IDs are case-sensitive. They are not meant to be human-readable. They are
 intended to be treated as fully opaque strings by clients.
 
-
 ### URIs
 
 There are two major kinds of referring to a resource in Matrix: matrix.to
@@ -707,13 +754,13 @@ history (a permalink).
 
 The Matrix URI scheme is defined as follows (`[]` enclose optional parts, `{}`
 enclose variables):
-```
+```nohighlight
 matrix:[//{authority}/]{type}/{id without sigil}[/{type}/{id without sigil}...][?{query}][#{fragment}]
 ```
 
 As a schema, this can be represented as:
 
-```
+```nohighlight
 MatrixURI = "matrix:" hier-part [ "?" query ] [ "#" fragment ]
 hier-part = [ "//" authority "/" ] path
 path = entity-descriptor ["/" entity-descriptor]
@@ -745,7 +792,7 @@ Specifically, the following mappings are used:
 * `r` for room aliases.
 * `u` for users.
 * `roomid` for room IDs (note the distinction from room aliases).
-* `e` for events, when after a room reference (`r` or `roomid`).
+* `e` for events, when after a room ID (`roomid`). Use of `e` after a room alias (`r`) is deprecated.
 
 {{% boxes/note %}}
 During development of this URI format, types of `user`, `room`, and `event`
@@ -755,6 +802,13 @@ wish to consider handling them as `u`, `r`, and `e` respectively.
 `roomid` was otherwise unchanged.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+{{% 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.
+{{% /boxes/note %}}
+
 The `id without sigil` is simply the identifier for the entity without the defined
 sigil. For example, `!room:example.org` becomes `room:example.org` (`!` is the sigil
 for room IDs). The sigils are described under the
@@ -799,7 +853,6 @@ Examples of common URIs are:
 <!-- Author's note: These examples should be consistent with the matrix.to counterparts. -->
 * Link to `#somewhere:example.org`: `matrix:r/somewhere:example.org`
 * Link to `!somewhere:example.org`: `matrix:roomid/somewhere:example.org?via=elsewhere.ca`
-* Link to `$event` in `#somewhere:example.org`: `matrix:r/somewhere:example.org/e/event`
 * Link to `$event` in `!somewhere:example.org`: `matrix:roomid/somewhere:example.org/e/event?via=elsewhere.ca`
 * Link to chat with `@alice:example.org`: `matrix:u/alice:example.org?action=chat`
 
@@ -809,15 +862,15 @@ A suggested client implementation algorithm is available in the
 #### matrix.to navigation
 
 {{% boxes/note %}}
-This namespacing existed prior to a `matrix:` scheme. This is **not**
-meant to be interpreted as an available web service - see below for more
-details.
+matrix.to is a Namespace URI which existed prior to a `matrix:` URI scheme.
+This is **not** meant to be interpreted as an available web service - see
+below for more details.
 {{% /boxes/note %}}
 
 A matrix.to URI has the following format, based upon the specification
 defined in [RFC 3986](https://tools.ietf.org/html/rfc3986):
 
-```
+```nohighlight
 https://matrix.to/#/<identifier>/<extra parameter>?<additional arguments>
 ```
 
@@ -843,10 +896,16 @@ Examples of matrix.to URIs are:
 <!-- Author's note: These examples should be consistent with the matrix scheme counterparts. -->
 * Link to `#somewhere:example.org`: `https://matrix.to/#/%23somewhere%3Aexample.org`
 * Link to `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org?via=elsewhere.ca`
-* Link to `$event` in `#somewhere:example.org`: `https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org`
 * Link to `$event` in `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org?via=elsewhere.ca`
 * Link to `@alice:example.org`: `https://matrix.to/#/%40alice%3Aexample.org`
 
+{{% boxes/note %}}
+{{% 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.
+{{% /boxes/note %}}
+
 {{% boxes/note %}}
 Historically, clients have not produced URIs which are fully encoded.
 Clients should try to interpret these cases to the best of their
@@ -883,8 +942,8 @@ A room (or room permalink) which isn't using a room alias should supply
 at least one server using `via` in the URI's query string. Multiple servers
 can be specified by including multuple `via` parameters.
 
-The values of `via` are intended to be passed along as the `server_name`
-parameters on the [Client Server `/join/{roomIdOrAlias}` API](/client-server-api/#post_matrixclientv3joinroomidoralias).
+The values of `via` are intended to be passed along on the
+[Client Server `/join/{roomIdOrAlias}` API](/client-server-api/#post_matrixclientv3joinroomidoralias).
 
 When generating room links and permalinks, the application should pick
 servers which have a high probability of being in the room in the
@@ -921,6 +980,50 @@ unique servers based on the following criteria:
     specify the servers it can. For example, a room with only 2 users in
     it would result in maximum 2 `via` parameters.
 
+### Opaque Identifiers
+
+The specification defines some identifiers to use the *Opaque Identifier
+Grammar*. This is a common grammar intended for non-user-visible identifiers
+which do not require parsing or interpretation (other than as a unique
+identifier).
+
+The grammar is defined as:
+
+* Identifiers must be entirely composed of the characters `[0-9]`, `[A-Z]`,
+  `[a-z]`, `-`, `.`, `_`, and `~`.
+* Unless otherwise specified, identifiers must be at least one character and at
+  most 255 characters in length.
+
+{{% boxes/note %}}
+The acceptable character set matches the unreserved character set in [RFC
+3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
+{{% /boxes/note %}}
+
+## Cryptographic key representation
+
+Sometimes it is necessary to present a private cryptographic key in the user
+interface.
+
+When this happens, the key SHOULD be presented as a string formatted as
+follows:
+
+1.  A byte array is created, consisting of two bytes `0x8B` and `0x01`,
+    followed by the raw key.
+2.  All the bytes in the array above, including the two header bytes,
+    are XORed together to form a parity byte. This parity byte is
+    appended to the byte array.
+3.  The byte array is encoded using base58, using the the alphabet
+    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
+4.  A space is added after every 4th character.
+
+When reading in a key, clients should disregard whitespace, and
+perform the reverse of steps 1 through 4.
+
+{{% boxes/note %}}
+The base58 alphabet is the same as that used for [Bitcoin
+addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart).
+{{% /boxes/note %}}
+
 ## 3PID Types
 
 Third-party Identifiers (3PIDs) represent identifiers on other

content/application-service-api.md

@@ -2,16 +2,14 @@
 title: "Application Service API"
 weight: 30
 type: docs
+description: |
+  The Matrix client-server API and server-server APIs provide a consistent,
+  self-contained federated messaging fabric but leave little room for custom
+  server-side behaviour such as gateways, filters, or extensible hooks. The
+  Application Service API defines a standard way to add this extensible
+  functionality, independent of the underlying homeserver implementation.
 ---
 
-The Matrix client-server API and server-server APIs provide the means to
-implement a consistent self-contained federated messaging fabric.
-However, they provide limited means of implementing custom server-side
-behaviour in Matrix (e.g. gateways, filters, extensible hooks etc). The
-Application Service API (AS API) defines a standard API to allow such
-extensible functionality to be implemented irrespective of the
-underlying homeserver implementation.
-
 ## Application Services
 
 Application services are passive and can only observe events from the
@@ -86,7 +84,7 @@ For the `users` namespace, application services can only register interest in
 homeserver). Events affecting users on other homeservers are not sent to an application
 service, even if the user happens to match the one of the `users` namespaces (unless,
 of course, the event affects a room that the application service is interested in
-for another room - for example, because there is another user in the room that the
+for another reason - for example, because there is another user in the room that the
 application service is interested in).
 
 For the `rooms` and `aliases` namespaces, all events in a matching room will be
@@ -178,13 +176,13 @@ The application service API provides a transaction API for sending a
 list of events. Each list of events includes a transaction ID, which
 works as follows:
 
-```
+```nohighlight
     Typical
     HS ---> AS : Homeserver sends events with transaction ID T.
        <---    : Application Service sends back 200 OK.
 ```
 
-```
+```nohighlight
     AS ACK Lost
     HS ---> AS : Homeserver sends events with transaction ID T.
        <-/-    : AS 200 OK is lost.
@@ -207,6 +205,39 @@ processed the events.
 
 {{% http-api spec="application-service" api="transactions" %}}
 
+##### Pushing ephemeral data
+
+{{% added-in v="1.13" %}}
+
+If the `receive_ephemeral` settings is enabled in the [registration](#registration)
+file, homeservers MUST send ephemeral data that is relevant to the application
+service via the transaction API, using the `ephemeral` property of the request's
+body. This property is an array that is effectively a combination of the
+`presence` and `ephemeral` sections of the client-server [`/sync`](/client-server-api/#get_matrixclientv3sync)
+API.
+
+There are currently three event types that can be delivered to an application
+service:
+
+- **[`m.presence`](/client-server-api/#mpresence)**: MUST be sent to the
+application service if the data would apply contextually. For example, a
+presence update for a user an application service shares a room with, or
+matching one of the application service's namespaces.
+- **[`m.typing`](/client-server-api/#mtyping)**: MUST be sent to the application
+service under the same rules as regular events, meaning that the application
+service must have registered interest in the room itself, or in a user that is
+in the room. The data MUST use the same format as the client-server API, with
+the addition of a `room_id` property at the top level to identify the room that
+they were sent in.
+- **[`m.receipt`](/client-server-api/#mreceipt)**: MUST be sent to the
+application service under the same rules as regular events, meaning that the
+application service must have registered interest in the room itself, or in a
+user that is in the room. The data MUST use the same format as the client-server
+API, with the addition of a `room_id` property at the top level to identify the
+room that they were sent in. [Private read receipts](/client-server-api/#private-read-receipts)
+MUST only be sent for users matching one of the application service's
+namespaces. Normal read receipts and threaded read receipts are always sent.
+
 #### Pinging
 
 {{% added-in v="1.7" %}}
@@ -225,7 +256,7 @@ have been omitted for brevity):
 
 **Typical**
 
-```
+```nohighlight
 AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
     HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
     HS <--- AS : 200 OK {}
@@ -234,7 +265,7 @@ AS <--- HS : 200 OK {"duration_ms": 123}
 
 **Incorrect `hs_token`**
 
-```
+```nohighlight
 AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
     HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
     HS <--- AS : 403 Forbidden {"errcode": "M_FORBIDDEN"}
@@ -243,7 +274,7 @@ AS <--- HS : 502 Bad Gateway {"errcode": "M_BAD_STATUS", "status": 403, "body":
 
 **Can't connect to appservice**
 
-```
+```nohighlight
 AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
     HS -/-> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
 AS <--- HS : 502 Bad Gateway {"errcode": "M_CONNECTION_FAILED"}
@@ -323,6 +354,7 @@ service would like to masquerade as.
 Inputs:
 -   Application service token (`as_token`)
 -   User ID in the AS namespace to act as.
+-   Device ID belonging to the User ID to act with.
 
 Notes:
 -   This applies to all aspects of the Client-Server API, except for
@@ -342,9 +374,19 @@ service's `user` namespaces. If the parameter is missing, the homeserver
 is to assume the application service intends to act as the user implied
 by the `sender_localpart` property of the registration.
 
+{{% added-in v="1.17" %}} Application services MAY similarly masquerade
+as a specific device ID belonging the user ID through use of the `device_id`
+query string parameter on the request. If the given device ID is not known
+to belong to the user, the server will return a 400 `M_UNKNOWN_DEVICE` error.
+If no `user_id` is supplied, the `device_id` MUST belong to the user implied
+by the `sender_localpart` property of the application service's registration.
+If no `device_id` is supplied, the homeserver is to assume the request is
+being made without a device ID and will fail to complete operations which
+require a device ID (such as uploading one-time keys).
+
 An example request would be:
 
-    GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org
+    GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org&device_id=ABC123
     Authorization: Bearer YourApplicationServiceTokenHere
 
 #### Timestamp massaging
@@ -384,6 +426,8 @@ imports and similar behaviour).
 
 #### Server admin style permissions
 
+{{% changed-in v="1.17" %}}
+
 The homeserver needs to give the application service *full control* over
 its namespace, both for users and for room aliases. This means that the
 AS should be able to manage any users and room alias in its namespace. No additional API
@@ -400,33 +444,59 @@ achieved by including the `as_token` on a `/register` request, along
 with a login type of `m.login.application_service` to set the desired
 user ID without a password.
 
+```http
 POST /_matrix/client/v3/register
 Authorization: Bearer YourApplicationServiceTokenHere
+```
 
-    Content:
+```json
 {
-      type: "m.login.application_service",
-      username: "_irc_example"
+  "type": "m.login.application_service",
+  "username": "_irc_example"
 }
+```
 
-Similarly, logging in as users needs API changes in order to allow the AS to
-log in without needing the user's password. This is achieved by including the
-`as_token` on a `/login` request, along with a login type of
-`m.login.application_service`:
+{{% boxes/note %}}
+{{% added-in v="1.17" %}}
+Servers MUST still allow application services to use the `/register` endpoint
+with a login type of `m.login.application_service` even if they don't support
+the [Legacy Authentication API](/client-server-api/#legacy-api).
+
+In that case application services MUST set the `"inhibit_login": true` parameter
+as they cannot use it to log in as users. If the `inhibit_login` parameter is
+not set to `true`, the server MUST return a 400 HTTP status code with an
+`M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
+{{% /boxes/note %}}
+
+Similarly, logging in as users using the [Legacy authentication API](/client-server-api/#legacy-api)
+needs API changes in order to allow the AS to log in without needing the user's
+password. This is achieved by including the `as_token` on a `/login` request,
+along with a login type of `m.login.application_service`:
 
 {{% added-in v="1.2" %}}
 
+```http
 POST /_matrix/client/v3/login
 Authorization: Bearer YourApplicationServiceTokenHere
+```
 
-    Content:
+```json
 {
-      type: "m.login.application_service",
+  "type": "m.login.application_service",
   "identifier": {
     "type": "m.id.user",
     "user": "_irc_example"
   }
 }
+```
+
+{{% boxes/note %}}
+{{% added-in v="1.17" %}}
+Application services MUST NOT use the `/login` endpoint if the server doesn't
+support the Legacy authentication API. If `/login` is called with the
+`m.login.application_service` login type the server MUST return a 400 HTTP
+status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
+{{% /boxes/note %}}
 
 Application services which attempt to create users or aliases *outside*
 of their defined namespaces, or log in as users outside of their defined
@@ -459,15 +529,47 @@ via the query string). It is expected that the application service use
 the transactions pushed to it to handle events rather than syncing with
 the user implied by `sender_localpart`.
 
-#### Application service room directories
+#### Published room directories
 
-Application services can maintain their own room directories for their
-defined third-party protocols. These room directories may be accessed by
+Application services can maintain their own published room directories for
+their defined third-party protocols. These directories may be accessed by
 clients through additional parameters on the `/publicRooms`
 client-server endpoint.
 
 {{% http-api spec="client-server" api="appservice_room_directory" %}}
 
+#### Device management
+
+{{% added-in v="1.17" %}}
+
+Application services need to be able to create and delete devices to manage the
+encryption for their users without having to rely on `/login`, which also
+generates an access token for the user, and which might not be available for
+homeservers that only support the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+
+##### Creating devices
+
+Application services can use the [`PUT /_matrix/client/v3/devices/{deviceId}`](/client-server-api/#put_matrixclientv3devicesdeviceid)
+endpoint to create new devices.
+
+##### Deleting devices
+
+The following endpoints used to delete devices MUST NOT require [User-Interactive
+Authentication](/client-server-api/#user-interactive-authentication-api) when
+used by an application service:
+
+* [`DELETE /_matrix/client/v3/devices/{deviceId}`](/client-server-api/#delete_matrixclientv3devicesdeviceid)
+* [`POST /_matrix/client/v3/delete_devices`](/client-server-api/#post_matrixclientv3delete_devices)
+
+#### Cross-signing
+
+{{% added-in v="1.17" %}}
+
+Appservices need to be able to verify themselves and replace their cross-signing
+keys, so the [`POST /_matrix/client/v3/keys/device_signing/upload`](/client-server-api/#post_matrixclientv3keysdevice_signingupload)
+endpoint MUST NOT require [User-Interactive Authentication](/client-server-api/#user-interactive-authentication-api)
+when used by an application service, even if cross-signing keys already exist.
+
 ### Referencing messages from a third-party network
 
 Application services should include an `external_url` in the `content`

content/changelog/_index.md

@@ -0,0 +1,8 @@
+---
+title: Changelog
+type: docs
+layout: changelog-index
+weight: 1000
+---
+
+<!-- This page will be redirected to the latest version's changelog -->

content/changelog/historical.md

@@ -1,18 +1,15 @@
 ---
-title: Changelog
+title: Historical versions
 type: docs
-weight: 1000
+outputs:
+  - html
 ---
 
-{{% changelog/changelog-description %}}
+Before version 1.1, versioning was applied at the level of individual API specifications.
+This section includes links to these versions of the APIs.
 
-{{% changelog/changelogs %}}
+## Client-Server API
 
-<h2 id="historical-versions" class="no-numbers">Historical versions</h2>
-
-Before version 1.1, versioning was applied at the level of individual API specifications. This section includes links to these versions of the APIs.
-
-* **Client-Server API**
   -   [r0.6.1](https://matrix.org/docs/spec/client_server/r0.6.1.html)
   -   [r0.6.0](https://matrix.org/docs/spec/client_server/r0.6.0.html)
   -   [r0.5.0](https://matrix.org/docs/spec/client_server/r0.5.0.html)
@@ -26,22 +23,26 @@ Before version 1.1, versioning was applied at the level of individual API specif
       The last draft before the spec was formally released in version
       r0.0.0.
 
-* **Server-Server API**
+## Server-Server API
+
   -   [r0.1.4](https://matrix.org/docs/spec/server_server/r0.1.4.html)
   -   [r0.1.3](https://matrix.org/docs/spec/server_server/r0.1.3.html)
   -   [r0.1.2](https://matrix.org/docs/spec/server_server/r0.1.2.html)
   -   [r0.1.1](https://matrix.org/docs/spec/server_server/r0.1.1.html)
   -   [r0.1.0](https://matrix.org/docs/spec/server_server/r0.1.0.html)
 
-* **Application Service API**
+## Application Service API
+
   -   [r0.1.1](https://matrix.org/docs/spec/application_service/r0.1.1.html)
   -   [r0.1.0](https://matrix.org/docs/spec/application_service/r0.1.0.html)
 
-* **Identity Service API**
+## Identity Service API
+
   -   [r0.3.0](https://matrix.org/docs/spec/identity_service/r0.3.0.html)
   -   [r0.2.1](https://matrix.org/docs/spec/identity_service/r0.2.1.html)
   -   [r0.2.0](https://matrix.org/docs/spec/identity_service/r0.2.0.html)
   -   [r0.1.0](https://matrix.org/docs/spec/identity_service/r0.1.0.html)
 
-* **Push Gateway API**
+## Push Gateway API
+
   -   [r0.1.0](https://matrix.org/docs/spec/push_gateway/r0.1.0.html)

content/changelog/v1.1.md

@@ -1,23 +1,15 @@
 ---
-date: 2021-11-09T00:00:00+0000
+title: v1.1 Changelog
+linkTitle: v1.1
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2021-11-09
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.1  = Replaced by the version number (eg: v1.2)
-    November 09, 2021     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.1
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.1">https://github.com/matrix-org/matrix-doc/tree/v1.1</a></td>
-<tr><th>Release date</th><td>November 09, 2021</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
+## Client-Server API
 
 
 <strong>Breaking Changes</strong>
@@ -110,7 +102,7 @@ Variables:
 - Fix documentation errors around `threepid_creds`. ([#3471](https://github.com/matrix-org/matrix-doc/issues/3471))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>New Endpoints</strong>
@@ -136,7 +128,7 @@ Variables:
 - Tweak the example PDU diagram to better demonstrate situations with multiple `prev_events`. ([#3340](https://github.com/matrix-org/matrix-doc/issues/3340))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -145,7 +137,7 @@ Variables:
 - Fix various typos throughout the specification. ([#2888](https://github.com/matrix-org/matrix-doc/issues/2888))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>New Endpoints</strong>
@@ -168,7 +160,7 @@ Variables:
 - Describe how [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) affects the `/versions` endpoint. ([#3459](https://github.com/matrix-org/matrix-doc/issues/3459))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 <strong>Spec Clarifications</strong>

content/changelog/v1.10.md

@@ -1,24 +1,15 @@
 ---
-date: 2024-03-22T09:59:45-06:00
+title: v1.10 Changelog
+linkTitle: v1.10
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2024-03-22
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.10  = Replaced by the version number (eg: v1.2)
-    March 22, 2024     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.10
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.10">https://github.com/matrix-org/matrix-spec/tree/v1.10</a></td>
-<tr><th>Release date</th><td>March 22, 2024</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-
-### Client-Server API
+## Client-Server API
 
 **Backwards Compatible Changes**
 
@@ -50,7 +41,7 @@ Variables:
 - Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010). ([#1763](https://github.com/matrix-org/matrix-spec/issues/1763))
 
 
-### Server-Server API
+## Server-Server API
 
 **Spec Clarifications**
 
@@ -59,36 +50,36 @@ Variables:
 - Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. ([#1741](https://github.com/matrix-org/matrix-spec/issues/1741))
 
 
-### Application Service API
+## Application Service API
 
 **Spec Clarifications**
 
 - Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. ([#1744](https://github.com/matrix-org/matrix-spec/issues/1744))
 
 
-### Identity Service API
+## Identity Service API
 
 No significant changes.
 
 
-### Push Gateway API
+## Push Gateway API
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 **Spec Clarifications**
 
 - For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. ([#1717](https://github.com/matrix-org/matrix-spec/issues/1717))
 
 
-### Appendices
+## Appendices
 
 No significant changes.
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 **Spec Clarifications**
 

content/changelog/v1.11.md

@@ -0,0 +1,161 @@
+---
+title: v1.11 Changelog
+linkTitle: v1.11
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2024-06-20
+---
+
+## Client-Server API
+
+**Deprecations**
+
+- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808))
+- Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**New Endpoints**
+
+- [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**Backwards Compatible Changes**
+
+- Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291). ([#1755](https://github.com/matrix-org/matrix-spec/issues/1755))
+- Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). ([#1757](https://github.com/matrix-org/matrix-spec/issues/1757))
+- Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692). ([#1812](https://github.com/matrix-org/matrix-spec/issues/1812))
+- Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191). ([#1816](https://github.com/matrix-org/matrix-spec/issues/1816))
+- Do not require UIA when first uploading cross-signing keys, as per [MSC3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967). ([#1828](https://github.com/matrix-org/matrix-spec/issues/1828))
+- Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). ([#1847](https://github.com/matrix-org/matrix-spec/issues/1847))
+- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**Spec Clarifications**
+
+- Add `/logout` and clarify the endpoints which do not take a JSON request body. ([#1644](https://github.com/matrix-org/matrix-spec/issues/1644))
+- Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response. ([#1776](https://github.com/matrix-org/matrix-spec/issues/1776))
+- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813))
+- Rename "recovery key" to "backup decryption key". ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819))
+- Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key). ([#1829](https://github.com/matrix-org/matrix-spec/issues/1829))
+- Fix various typos throughout the specification. ([#1832](https://github.com/matrix-org/matrix-spec/issues/1832), [#1841](https://github.com/matrix-org/matrix-spec/issues/1841), [#1852](https://github.com/matrix-org/matrix-spec/issues/1852), [#1853](https://github.com/matrix-org/matrix-spec/issues/1853))
+- Specify the encoding to be used when generating QR codes for device verification. ([#1839](https://github.com/matrix-org/matrix-spec/issues/1839))
+- Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints. ([#1843](https://github.com/matrix-org/matrix-spec/issues/1843))
+- Use RFC 2119 keywords more consistently. ([#1846](https://github.com/matrix-org/matrix-spec/issues/1846), [#1861](https://github.com/matrix-org/matrix-spec/issues/1861))
+- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850))
+- Clarify that relations recursion should be capped at a certain depth. ([#1854](https://github.com/matrix-org/matrix-spec/issues/1854))
+- Add missing secrets, third-party invites and room tagging modules to feature profiles table. ([#1860](https://github.com/matrix-org/matrix-spec/issues/1860))
+- Clarify when server name is used and link to the definition. ([#1862](https://github.com/matrix-org/matrix-spec/issues/1862))
+- Clarify where keys reside when checking an `m.room.encrypted` event. ([#1863](https://github.com/matrix-org/matrix-spec/issues/1863))
+- Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. ([#1872](https://github.com/matrix-org/matrix-spec/issues/1872))
+
+
+## Server-Server API
+
+**Deprecations**
+
+- Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**New Endpoints**
+
+- [`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+- [`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858))
+
+**Backwards Compatible Changes**
+
+- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858), [#1869](https://github.com/matrix-org/matrix-spec/issues/1869))
+
+**Spec Clarifications**
+
+- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813))
+- Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list. ([#1818](https://github.com/matrix-org/matrix-spec/issues/1818))
+- Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. ([#1834](https://github.com/matrix-org/matrix-spec/issues/1834), [#1840](https://github.com/matrix-org/matrix-spec/issues/1840))
+- Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. ([#1844](https://github.com/matrix-org/matrix-spec/issues/1844))
+- Fix various typos throughout the specification. ([#1877](https://github.com/matrix-org/matrix-spec/issues/1877))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Clarify that appservices should be notified of events relating to the `sender_localpart` user. ([#1810](https://github.com/matrix-org/matrix-spec/issues/1810))
+
+
+## Identity Service API
+
+**Deprecations**
+
+- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808))
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- Clarify that redaction events are still subject to all applicable auth rules. ([#1824](https://github.com/matrix-org/matrix-spec/issues/1824))
+- Fix various typos throughout the specification. ([#1827](https://github.com/matrix-org/matrix-spec/issues/1827), [#1848](https://github.com/matrix-org/matrix-spec/issues/1848))
+- Fix the rendering of the event format for room versions 1 and 2. ([#1883](https://github.com/matrix-org/matrix-spec/issues/1883))
+- Generate the Table of Contents with Hugo rather than JavaScript. ([#1884](https://github.com/matrix-org/matrix-spec/issues/1884))
+
+
+## Appendices
+
+**Deprecations**
+
+- Deprecate linking to events in rooms identified by alias, as per [MSC4132](https://github.com/matrix-org/matrix-spec-proposals/pull/4132). ([#1823](https://github.com/matrix-org/matrix-spec/issues/1823))
+
+**Spec Clarifications**
+
+- Define 'Opaque Identifier Grammar'. ([#1791](https://github.com/matrix-org/matrix-spec/issues/1791))
+- Define common cryptographic key representation. ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819))
+- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850))
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Update the spec release process and related documentation. ([#1759](https://github.com/matrix-org/matrix-spec/issues/1759))
+- Fix npm release script for `@matrix-org/spec`. ([#1765](https://github.com/matrix-org/matrix-spec/issues/1765))
+- Formatting fixes in `CONTRIBUTING.rst`. ([#1769](https://github.com/matrix-org/matrix-spec/issues/1769))
+- Improve rendering on mobile devices. ([#1770](https://github.com/matrix-org/matrix-spec/issues/1770), [#1771](https://github.com/matrix-org/matrix-spec/issues/1771))
+- Fix the OpenAPI definition of the security schemes. ([#1772](https://github.com/matrix-org/matrix-spec/issues/1772))
+- Simplify uses of `resolve-refs` partial. ([#1773](https://github.com/matrix-org/matrix-spec/issues/1773))
+- Fix Hugo warnings. ([#1775](https://github.com/matrix-org/matrix-spec/issues/1775), [#1788](https://github.com/matrix-org/matrix-spec/issues/1788))
+- Fix `github-labels.rst`. ([#1781](https://github.com/matrix-org/matrix-spec/issues/1781))
+- Update dependencies. ([#1786](https://github.com/matrix-org/matrix-spec/issues/1786), [#1803](https://github.com/matrix-org/matrix-spec/issues/1803), [#1804](https://github.com/matrix-org/matrix-spec/issues/1804))
+- Solve `allOf` recursively in OpenAPI and JSON Schemas. ([#1787](https://github.com/matrix-org/matrix-spec/issues/1787))
+- Fix property type resolution in `render-object-table` partial. ([#1789](https://github.com/matrix-org/matrix-spec/issues/1789))
+- Factor out common definition of `Tag` type. ([#1793](https://github.com/matrix-org/matrix-spec/issues/1793))
+- Update the version of Hugo used to render the spec to v0.124.1. ([#1794](https://github.com/matrix-org/matrix-spec/issues/1794))
+- Add support for pattern formats for `patternProperties`. ([#1796](https://github.com/matrix-org/matrix-spec/issues/1796))
+- Clean up unnecessary `allOf`s in OpenAPI definitions. ([#1797](https://github.com/matrix-org/matrix-spec/issues/1797))
+- Show information about "Additional Properties" in object tables. ([#1798](https://github.com/matrix-org/matrix-spec/issues/1798))
+- Fix anchors for schemas under `oneOf`. ([#1799](https://github.com/matrix-org/matrix-spec/issues/1799))
+- Use reference to `OneTimeKeys` schema in OpenAPI definitions. ([#1800](https://github.com/matrix-org/matrix-spec/issues/1800))
+- Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`. ([#1801](https://github.com/matrix-org/matrix-spec/issues/1801))
+- Add anchors in `definition` shortcode. ([#1802](https://github.com/matrix-org/matrix-spec/issues/1802))
+- Set python version for the Towncrier CI job. ([#1805](https://github.com/matrix-org/matrix-spec/issues/1805))
+- Replace `set-output` with environment files in CI. ([#1806](https://github.com/matrix-org/matrix-spec/issues/1806))
+- Render response headers. ([#1809](https://github.com/matrix-org/matrix-spec/issues/1809))
+- Use `patternProperties` in more places with supported formats. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813))
+- Add support for rendering string formats. ([#1814](https://github.com/matrix-org/matrix-spec/issues/1814))
+- Refactor the OpenAPI definitions of the content repository endpoints. ([#1822](https://github.com/matrix-org/matrix-spec/issues/1822))
+- Clean up pull request template. ([#1831](https://github.com/matrix-org/matrix-spec/issues/1831))
+- Do not add empty arrays to examples. ([#1849](https://github.com/matrix-org/matrix-spec/issues/1849))
+- Generate the Table of Contents with Hugo rather than JavaScript. ([#1851](https://github.com/matrix-org/matrix-spec/issues/1851), [#1885](https://github.com/matrix-org/matrix-spec/issues/1885))
+- Fix syntax errors in the spec release issue template. ([#1856](https://github.com/matrix-org/matrix-spec/issues/1856))
+- Use environment variables for Netlify build job. ([#1865](https://github.com/matrix-org/matrix-spec/issues/1865))
+- Render added/changed in info on request and response content types. ([#1876](https://github.com/matrix-org/matrix-spec/issues/1876))
+- Fix validation errors in generated HTML. ([#1880](https://github.com/matrix-org/matrix-spec/issues/1880))
+- Ensure most generated HTML IDs are unique. ([#1881](https://github.com/matrix-org/matrix-spec/issues/1881))
+- Allow to specify a prefix for generated HTML IDs of API endpoints. ([#1882](https://github.com/matrix-org/matrix-spec/issues/1882))

content/changelog/v1.12.md

@@ -0,0 +1,113 @@
+---
+title: v1.12 Changelog
+linkTitle: v1.12
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2024-10-07
+---
+
+## Client-Server API
+
+**Deprecations**
+
+- Deprecate the `server_name` query parameter on `POST /_matrix/client/v3/join/{roomIdOrAlias}` and `POST /_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). ([#1933](https://github.com/matrix-org/matrix-spec/issues/1933))
+
+**Removed Endpoints**
+
+- Remove references to device-specific push rules. ([#1842](https://github.com/matrix-org/matrix-spec/issues/1842))
+- Remove the deprecated name attribute on HTML anchor elements, as per [MSC4159](https://github.com/matrix-org/matrix-spec-proposals/pull/4159). ([#1870](https://github.com/matrix-org/matrix-spec/issues/1870))
+
+**Backwards Compatible Changes**
+
+- Add 403 responses on `GET /_matrix/client/v3/profile/{userId}/avatar_url` and `GET /_matrix/client/v3/profile/{userId}/displayname`, as per [MSC4170](https://github.com/matrix-org/matrix-spec-proposals/pull/4170). ([#1867](https://github.com/matrix-org/matrix-spec/issues/1867))
+- Add support for marking rooms as unread, as per [MSC2867](https://github.com/matrix-org/matrix-spec-proposals/pull/2867). ([#1895](https://github.com/matrix-org/matrix-spec/issues/1895), [#1941](https://github.com/matrix-org/matrix-spec/issues/1941))
+- Add `via` query parameter on `POST /_matrix/client/v3/join/{roomIdOrAlias}` and `POST /_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). ([#1933](https://github.com/matrix-org/matrix-spec/issues/1933))
+- Add account locking, as per [MSC3939](https://github.com/matrix-org/matrix-spec-proposals/pull/3939). ([#1934](https://github.com/matrix-org/matrix-spec/issues/1934))
+- Guest accounts can now download/thumbnail media from the new authenticated endpoints, as per [MSC4189](https://github.com/matrix-org/matrix-spec-proposals/pull/4189). ([#1959](https://github.com/matrix-org/matrix-spec/issues/1959))
+
+**Spec Clarifications**
+
+- Rename and sort the modules in the feature profiles table for easier skimming. ([#1855](https://github.com/matrix-org/matrix-spec/issues/1855))
+- Clarify that room avatars cannot be encrypted. ([#1871](https://github.com/matrix-org/matrix-spec/issues/1871))
+- Document the acronyms and alternate names for the "Secrets" section. ([#1875](https://github.com/matrix-org/matrix-spec/issues/1875))
+- Improve recommendation for how to form transaction IDs. ([#1888](https://github.com/matrix-org/matrix-spec/issues/1888))
+- Clarify that the deprecated `dont_notify` and `coalesce` push rule actions MUST be ignored, not rejected. ([#1890](https://github.com/matrix-org/matrix-spec/issues/1890))
+- Fix various typos throughout the specification. ([#1892](https://github.com/matrix-org/matrix-spec/issues/1892))
+- Add missing references to `m.set_displayname`, `m.set_avatar_url`, and `m.3pid_changes` in capabilities table. ([#1897](https://github.com/matrix-org/matrix-spec/issues/1897))
+- Clarify that the fallback login page calls `window.matrixLogin.onLogin` instead of `window.onLogin`. ([#1899](https://github.com/matrix-org/matrix-spec/issues/1899))
+- Remove confusing description of restricted rooms with no valid conditions. ([#1903](https://github.com/matrix-org/matrix-spec/issues/1903))
+- Clarify that `window.matrixLogin.onLogin` is called with the response body of `POST /_matrix/client/v3/login`. ([#1905](https://github.com/matrix-org/matrix-spec/issues/1905))
+- Document the `m.get_login_token` capability, as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). ([#1908](https://github.com/matrix-org/matrix-spec/issues/1908))
+- Clarify that the `User identifier` object in `POST /_matrix/client/v3/login` contains additional properties that depend on the identification type. ([#1909](https://github.com/matrix-org/matrix-spec/issues/1909))
+- Don't mention that `GET /_matrix/client/v3/profile/{userId}` can return additional properties because this is true for almost every endpoint. ([#1910](https://github.com/matrix-org/matrix-spec/issues/1910))
+- Improve wording of the unauthenticated media deprecation box. Contributed by @HarHarLinks. ([#1916](https://github.com/matrix-org/matrix-spec/issues/1916))
+- Additional properties in `GET /.well-known/matrix/client` don't have to be objects. ([#1920](https://github.com/matrix-org/matrix-spec/issues/1920))
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+- Specify `Content-Type` and `Content-Disposition` usage in the media repo, as per [MSC2701](https://github.com/matrix-org/matrix-spec-proposals/pull/2701) and [MSC2702](https://github.com/matrix-org/matrix-spec-proposals/pull/2702). ([#1935](https://github.com/matrix-org/matrix-spec/issues/1935))
+- Additional keys in `GET /_matrix/client/v3/capabilities` don't have to be objects. ([#1945](https://github.com/matrix-org/matrix-spec/issues/1945))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Add 403 response on `GET /_matrix/federation/v1/query/profile`, as per [MSC4170](https://github.com/matrix-org/matrix-spec-proposals/pull/4170). ([#1867](https://github.com/matrix-org/matrix-spec/issues/1867))
+
+**Spec Clarifications**
+
+- Remove `origin` field from PDU example because it doesn't exist in the schema anymore. ([#1918](https://github.com/matrix-org/matrix-spec/issues/1918))
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+- Fix required fields in `GET /_matrix/key/v2/server` response schema. ([#1930](https://github.com/matrix-org/matrix-spec/issues/1930))
+- Use "server name" instead of "DNS name" to avoid confusion with the "DNS name" component of "server names" as defined in the appendices. ([#1946](https://github.com/matrix-org/matrix-spec/issues/1946))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Identity Service API
+
+**Spec Clarifications**
+
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Push Gateway API
+
+**Spec Clarifications**
+
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- Fix a formatting issue in state resolution v2. ([#1896](https://github.com/matrix-org/matrix-spec/issues/1896))
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- The Matrix.org Foundation no longer requires "real" or "legally identifiable" names in order to contribute to projects. ([#1886](https://github.com/matrix-org/matrix-spec/issues/1886), [#1914](https://github.com/matrix-org/matrix-spec/issues/1914))
+- Document the `removal` changelog category. ([#1907](https://github.com/matrix-org/matrix-spec/issues/1907))
+- Use dedicated fonts for better support of mathematical symbols. ([#1919](https://github.com/matrix-org/matrix-spec/issues/1919))
+- Document that the spec uses [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) keywords. Contributed by @HarHarLinks. ([#1928](https://github.com/matrix-org/matrix-spec/issues/1928))
+- Provide markdown checklists for changelogs under `/changelog/$VERSION/checklist.md`. ([#1937](https://github.com/matrix-org/matrix-spec/issues/1937), [#1954](https://github.com/matrix-org/matrix-spec/issues/1954))
+- Add the `deprecated` field to properties of OpenAPI definitions and JSON Schemas. ([#1940](https://github.com/matrix-org/matrix-spec/issues/1940))
+- Use relative permalink to redirect to latest changelog. ([#1956](https://github.com/matrix-org/matrix-spec/issues/1956))

content/changelog/v1.13.md

@@ -0,0 +1,108 @@
+---
+title: v1.13 Changelog
+linkTitle: v1.13
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2024-12-19
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `POST /_matrix/client/v3/rooms/{roomId}/report`, as per [MSC4151](https://github.com/matrix-org/matrix-spec-proposals/pull/4151). ([#1938](https://github.com/matrix-org/matrix-spec/issues/1938), [#2028](https://github.com/matrix-org/matrix-spec/issues/2028))
+
+**Backwards Compatible Changes**
+
+- Add error codes to requestToken endpoints, as per [MSC4178](https://github.com/matrix-org/matrix-spec-proposals/pull/4178). ([#1944](https://github.com/matrix-org/matrix-spec/issues/1944))
+- Remove reply fallbacks, as per [MSC2781](https://github.com/matrix-org/matrix-spec-proposals/issues/2781). ([#1994](https://github.com/matrix-org/matrix-spec/issues/1994))
+- Clarify the allowed HTTP methods in CORS responses, as per [MSC4138](https://github.com/matrix-org/matrix-spec-proposals/pull/4138). ([#1995](https://github.com/matrix-org/matrix-spec/issues/1995), [#2011](https://github.com/matrix-org/matrix-spec/issues/2011))
+- Add new `M_USER_SUSPENDED` error code behaviour, as per [MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823). ([#2014](https://github.com/matrix-org/matrix-spec/issues/2014))
+
+**Spec Clarifications**
+
+- The `reason` parameter in `POST /_matrix/client/v3/rooms/{roomId}/report/{eventId}` can be omitted instead of left blank, as per [MSC2414](https://github.com/matrix-org/matrix-spec-proposals/pull/2414). ([#1938](https://github.com/matrix-org/matrix-spec/issues/1938))
+- Correct OpenAPI specification for query parameters to `GET /_matrix/client/v3/thirdparty/location/{protocol}` endpoint. ([#1947](https://github.com/matrix-org/matrix-spec/issues/1947))
+- Sort VoIP events semantically. ([#1967](https://github.com/matrix-org/matrix-spec/issues/1967))
+- Clarify that servers must forward custom keys in `PusherData` when sending notifications to the push gateway. ([#1973](https://github.com/matrix-org/matrix-spec/issues/1973))
+- Clarify formats of string types. ([#1978](https://github.com/matrix-org/matrix-spec/issues/1978), [#1979](https://github.com/matrix-org/matrix-spec/issues/1979), [#1980](https://github.com/matrix-org/matrix-spec/issues/1980))
+- Clarify that the async upload endpoint will return 404 in some cases. ([#1983](https://github.com/matrix-org/matrix-spec/issues/1983))
+- Remove distinction between `StateFilter` and `RoomEventFilter`. ([#2015](https://github.com/matrix-org/matrix-spec/issues/2015))
+- Add hyperlinks throughout the specification. ([#2016](https://github.com/matrix-org/matrix-spec/issues/2016))
+- Use `json` instead of `json5` for syntax highlighting. ([#2017](https://github.com/matrix-org/matrix-spec/issues/2017))
+- Specify order that one-time keys are issued by `/keys/claim`, as per [MSC4225](https://github.com/matrix-org/matrix-spec-proposals/pull/4225). ([#2029](https://github.com/matrix-org/matrix-spec/issues/2029))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Make ACLs apply to EDUs, as per [MSC4163](https://github.com/matrix-org/matrix-spec-proposals/pull/4163). ([#2004](https://github.com/matrix-org/matrix-spec/issues/2004))
+
+**Spec Clarifications**
+
+- Add 403 error response to `/_matrix/federation/v1/state_ids/{roomId}`. ([#1926](https://github.com/matrix-org/matrix-spec/issues/1926))
+
+
+## Application Service API
+
+**Backwards Compatible Changes**
+
+- Allow sending ephemeral data to application services, as per [MSC2409](https://github.com/matrix-org/matrix-spec-proposals/pull/2409). ([#2018](https://github.com/matrix-org/matrix-spec/issues/2018))
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+**Spec Clarifications**
+
+- Document the schema of `PusherData`. ([#1968](https://github.com/matrix-org/matrix-spec/issues/1968))
+- The path of HTTP pusher URLs is fixed to `/_matrix/push/v1/notify`. ([#1974](https://github.com/matrix-org/matrix-spec/issues/1974))
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- Clarify rule 4.3.1 of the auth rules in room version 11 to state which event's `sender` the `state_key` needs to match. ([#2024](https://github.com/matrix-org/matrix-spec/issues/2024))
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Remove note about reference implementations. ([#1966](https://github.com/matrix-org/matrix-spec/issues/1966))
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Add `x-weight` property for sorting events rendered with the `event-group` shortcode. ([#1967](https://github.com/matrix-org/matrix-spec/issues/1967))
+- Enforce consistent vertical spacing between paragraphs in endpoint definitions. ([#1969](https://github.com/matrix-org/matrix-spec/issues/1969), [#2005](https://github.com/matrix-org/matrix-spec/issues/2005))
+- Remove `boxes/added-in-paragraph` shortcode. ([#1970](https://github.com/matrix-org/matrix-spec/issues/1970))
+- Remove `withVersioning` parameter of `rver-fragment` shortcode. ([#1971](https://github.com/matrix-org/matrix-spec/issues/1971))
+- Remove `span` element from `added-in` and `changed-in` shortcodes. ([#1972](https://github.com/matrix-org/matrix-spec/issues/1972))
+- Fix formatting of `added-in` and `changed-in` shortcodes by using `%` delimiter. ([#1975](https://github.com/matrix-org/matrix-spec/issues/1975))
+- Remove CSS workaround for scroll-anchoring. ([#1976](https://github.com/matrix-org/matrix-spec/issues/1976))
+- Rename `custom-formats.yaml` to `string-formats.yaml` and update its docs. ([#1977](https://github.com/matrix-org/matrix-spec/issues/1977))
+- Fix relative URLs when serving the specification with a custom `baseURL`. ([#1984](https://github.com/matrix-org/matrix-spec/issues/1984), [#1997](https://github.com/matrix-org/matrix-spec/issues/1997))
+- Rename `.htmltest.yaml` to `.htmltest.yml`. ([#1985](https://github.com/matrix-org/matrix-spec/issues/1985))
+- Improve the JS script to highlight the current ToC entry. ([#1991](https://github.com/matrix-org/matrix-spec/issues/1991), [#2002](https://github.com/matrix-org/matrix-spec/issues/2002))
+- Upgrade docsy to 0.11.0 and hugo to 0.139.0. ([#1996](https://github.com/matrix-org/matrix-spec/issues/1996), [#2007](https://github.com/matrix-org/matrix-spec/issues/2007))
+- Improve the quality of the rendered diagrams ([#1999](https://github.com/matrix-org/matrix-spec/issues/1999))
+- Update the Inter font and allow the browser to render the page before it is loaded ([#2000](https://github.com/matrix-org/matrix-spec/issues/2000))
+- Use a proper Matrix favicon ([#2001](https://github.com/matrix-org/matrix-spec/issues/2001))
+- Clean up unused CSS classes in `openapi/render-operation` partial. ([#2003](https://github.com/matrix-org/matrix-spec/issues/2003))
+- Fix `changed-in` partial when used with multiple paragraphs. ([#2006](https://github.com/matrix-org/matrix-spec/issues/2006))
+- Optimize generated CSS by removing unused selectors. ([#2008](https://github.com/matrix-org/matrix-spec/issues/2008))
+- Remove trailing slash on void HTML elements. ([#2009](https://github.com/matrix-org/matrix-spec/issues/2009))
+- Remove `type` and `language` attributes of `script` element. ([#2021](https://github.com/matrix-org/matrix-spec/issues/2021))
+- Change the accessible role of info boxes to `note`. ([#2022](https://github.com/matrix-org/matrix-spec/issues/2022))

content/changelog/v1.14.md

@@ -0,0 +1,93 @@
+---
+title: v1.14 Changelog
+linkTitle: v1.14
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-03-27
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). ([#2093](https://github.com/matrix-org/matrix-spec/issues/2093))
+
+**Removed Endpoints**
+
+- Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). ([#2059](https://github.com/matrix-org/matrix-spec/issues/2059))
+
+**Spec Clarifications**
+
+- The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. ([#2036](https://github.com/matrix-org/matrix-spec/issues/2036))
+- Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. ([#2038](https://github.com/matrix-org/matrix-spec/issues/2038))
+- Clarify formats of string types. ([#2046](https://github.com/matrix-org/matrix-spec/issues/2046))
+- Fix various typos throughout the specification. ([#2047](https://github.com/matrix-org/matrix-spec/issues/2047), [#2048](https://github.com/matrix-org/matrix-spec/issues/2048), [#2080](https://github.com/matrix-org/matrix-spec/issues/2080), [#2091](https://github.com/matrix-org/matrix-spec/issues/2091))
+- Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. ([#2051](https://github.com/matrix-org/matrix-spec/issues/2051))
+- Applying redactions is a SHOULD for clients. ([#2055](https://github.com/matrix-org/matrix-spec/issues/2055))
+- Clarify which rooms are returned from `/hierarchy`. ([#2064](https://github.com/matrix-org/matrix-spec/issues/2064))
+- Clients can choose which history visibility options they offer to users when creating rooms. ([#2072](https://github.com/matrix-org/matrix-spec/issues/2072))
+
+
+## Server-Server API
+
+**Spec Clarifications**
+
+- Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. ([#2050](https://github.com/matrix-org/matrix-spec/issues/2050))
+- Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. ([#2063](https://github.com/matrix-org/matrix-spec/issues/2063))
+- Remove an erroneous `room_id` field in a few examples. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
+
+
+## Application Service API
+
+No significant changes.
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Backwards Compatible Changes**
+
+- Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). ([#2105](https://github.com/matrix-org/matrix-spec/issues/2105))
+
+**Spec Clarifications**
+
+- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
+- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
+- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
+- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. ([#1506](https://github.com/matrix-org/matrix-spec/issues/1506))
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Generate the changelog release info with Hugo, rather than the changelog generation script. ([#2033](https://github.com/matrix-org/matrix-spec/issues/2033))
+- Update release steps documentation. ([#2041](https://github.com/matrix-org/matrix-spec/issues/2041))
+- Remove unused `release_date` from Hugo config. ([#2042](https://github.com/matrix-org/matrix-spec/issues/2042))
+- Clarify that v1.0 of Matrix was a release prior to the current global versioning system. ([#2045](https://github.com/matrix-org/matrix-spec/issues/2045))
+- Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. ([#2049](https://github.com/matrix-org/matrix-spec/issues/2049))
+- Fix the version of the Identity Service API when Matrix 1.0 was introduced. ([#2061](https://github.com/matrix-org/matrix-spec/issues/2061))
+- Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. ([#2069](https://github.com/matrix-org/matrix-spec/issues/2069))
+- Deduplicate the definition of `RoomKeysUpdateResponse`. ([#2073](https://github.com/matrix-org/matrix-spec/issues/2073))
+- Deduplicate the definitions of `Invite3pid`. ([#2074](https://github.com/matrix-org/matrix-spec/issues/2074))
+- Support more locations for examples in OpenAPI definitions and JSON schemas. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
+- Add link to the git commit for the unstable changelog. ([#2078](https://github.com/matrix-org/matrix-spec/issues/2078))

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/changelog/v1.16.md

@@ -0,0 +1,103 @@
+---
+title: v1.16 Changelog
+linkTitle: v1.16
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-09-17
+---
+
+## Client-Server API
+
+**Deprecations**
+
+- Deprecate `m.set_avatar_url` and `m.set_displayname` capabilities, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). ([#2071](https://github.com/matrix-org/matrix-spec/issues/2071))
+
+**Removed Endpoints**
+
+- Remove unintentional intentional mentions in replies, as per [MSC4142](https://github.com/matrix-org/matrix-spec-proposals/pull/4142). ([#2210](https://github.com/matrix-org/matrix-spec/issues/2210))
+
+**Backwards Compatible Changes**
+
+- Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). ([#2071](https://github.com/matrix-org/matrix-spec/issues/2071))
+- Add `format` query parameter to `GET /state/{eventType}/{stateKey}` to allow fetching metadata of a specific state event. ([#2175](https://github.com/matrix-org/matrix-spec/issues/2175))
+- Add the `use_state_after` query parameter and `state_after` response property to `GET /sync`, as per [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/issues/4222). ([#2187](https://github.com/matrix-org/matrix-spec/issues/2187))
+- When upgrading rooms to [room version 12](/rooms/v12), `additional_creators` may be specified on the [`POST /_matrix/client/v3/rooms/{roomId}/upgrade`](/client-server-api/#post_matrixclientv3roomsroomidupgrade) endpoint, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- When creating rooms with [room version 12](/rooms/v12), the `trusted_private_chat` preset should merge the invitees into the supplied `content.additional_creators` in the resulting room, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- In [room version 12](/rooms/v12), the power level of room creators is now infinitely high as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- In [room version 12](/rooms/v12), room IDs no longer have a domain component as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- When creating rooms with [room version 12](/rooms/v12), the initial power levels will restrict the ability to upgrade rooms by default, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- Add a profile field for a user's time zone, as per [MSC4175](https://github.com/matrix-org/matrix-spec-proposals/pull/4175). ([#2206](https://github.com/matrix-org/matrix-spec/issues/2206))
+- Invites and knocks are now expected to contain the `m.room.create` event in their stripped state entries, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). ([#2207](https://github.com/matrix-org/matrix-spec/issues/2207))
+
+**Spec Clarifications**
+
+- Clarify that `format` is required if `formatted_body` is specified. ([#2167](https://github.com/matrix-org/matrix-spec/issues/2167))
+- The `latest_event` in an aggregated set of thread events uses the same format as the event itself. ([#2169](https://github.com/matrix-org/matrix-spec/issues/2169))
+- Fix various typos throughout the specification. ([#2171](https://github.com/matrix-org/matrix-spec/issues/2171), [#2177](https://github.com/matrix-org/matrix-spec/issues/2177), [#2179](https://github.com/matrix-org/matrix-spec/issues/2179))
+- Clarify that clients should replace events with the most recent replacement by `origin_server_ts`. ([#2190](https://github.com/matrix-org/matrix-spec/issues/2190))
+- Fix `/sync` flow referencing incorrect parameter to use with `/messages`. ([#2195](https://github.com/matrix-org/matrix-spec/issues/2195))
+- Clarify wording around the `world_readable` history visibility setting. Contributed by @HarHarLinks. ([#2204](https://github.com/matrix-org/matrix-spec/issues/2204))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- `invite_room_state` and `knock_room_state` now have additional requirements and validation depending on the room version, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). ([#2207](https://github.com/matrix-org/matrix-spec/issues/2207))
+
+
+## Application Service API
+
+No significant changes.
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Backwards Compatible Changes**
+
+- Room IDs in room version 12 are now the event ID of the create event with the normal room ID sigil (`!`), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- Room creators are formalized in room version 12 and have infinitely high power level, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- State Resolution is updated in room version 12 to reduce the opportunity for "state resets", as per [MSC4297](https://github.com/matrix-org/matrix-spec-proposals/pull/4297). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- The default room version is now room version 12, though servers SHOULD keep using room version 11 for a little while, as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- Add [room version 12](/rooms/v12) as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193), [#2199](https://github.com/matrix-org/matrix-spec/issues/2199))
+
+**Spec Clarifications**
+
+- In room versions 1 through 12, an event's `auth_events` have always needed to belong to the same room as per [MSC4307](https://github.com/matrix-org/matrix-spec-proposals/pull/4307). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+
+
+## Appendices
+
+**Backwards Compatible Changes**
+
+- Room IDs can now appear without a domain component in [room version 12](/rooms/v12), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+
+
+## Internal Changes/Tooling
+
+**Backwards Compatible Changes**
+
+- Add "placeholder MSC" process definition. ([#2157](https://github.com/matrix-org/matrix-spec/issues/2157))
+
+**Spec Clarifications**
+
+- Declare the Application Service Registration schema to follow JSON Schema spec 2020-12. ([#2132](https://github.com/matrix-org/matrix-spec/issues/2132))
+- Declare the event schemas to follow JSON Schema spec 2020-12. ([#2132](https://github.com/matrix-org/matrix-spec/issues/2132))
+- Upgrade the docsy theme to version 0.12.0. ([#2160](https://github.com/matrix-org/matrix-spec/issues/2160))
+- GitHub actions are now building the OpenAPI `spec/identity-service-api/api.json` file. ([#2172](https://github.com/matrix-org/matrix-spec/issues/2172))
+- Minor fixes to JSON schemas. ([#2182](https://github.com/matrix-org/matrix-spec/issues/2182))
+- Specify a correct spelling for "display name". ([#2189](https://github.com/matrix-org/matrix-spec/issues/2189))
+- Fix a grammatical typo on the Matrix Spec Process documentation page. ([#2205](https://github.com/matrix-org/matrix-spec/issues/2205))

content/changelog/v1.17.md

@@ -0,0 +1,91 @@
+---
+title: v1.17 Changelog
+linkTitle: v1.17
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-12-18
+---
+
+## Client-Server API
+
+**Removed Endpoints**
+
+- Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210). ([#2186](https://github.com/matrix-org/matrix-spec/issues/2186))
+
+**Backwards Compatible Changes**
+
+- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
+- Add the `m.oauth` authentication type for User-Interactive Authentication, as per [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/pull/4312). ([#2234](https://github.com/matrix-org/matrix-spec/issues/2234))
+- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
+
+**Spec Clarifications**
+
+- Push rule IDs are globally unique within their kind. ([#2214](https://github.com/matrix-org/matrix-spec/issues/2214))
+- Don't advertise `creator` field in description of room creation. ([#2215](https://github.com/matrix-org/matrix-spec/issues/2215))
+- `room_id` is required for peeking via `/_matrix/client/v3/events`. ([#2216](https://github.com/matrix-org/matrix-spec/issues/2216))
+- The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment. ([#2217](https://github.com/matrix-org/matrix-spec/issues/2217))
+- Add note to each endpoint that uses capability negotiation. ([#2223](https://github.com/matrix-org/matrix-spec/issues/2223))
+- Additional OpenGraph properties can be present in URL previews. ([#2225](https://github.com/matrix-org/matrix-spec/issues/2225))
+- Clarify the special casing of membership events and redactions in power levels. ([#2231](https://github.com/matrix-org/matrix-spec/issues/2231))
+- `M_RESOURCE_LIMIT_EXCEEDED` is now listed as a common error code. ([#2232](https://github.com/matrix-org/matrix-spec/issues/2232))
+- Add `m.login.terms` to enumeration of authentication types. ([#2233](https://github.com/matrix-org/matrix-spec/issues/2233))
+- Clarify how to use `state_after` ahead of declaring full support for its spec version. ([#2240](https://github.com/matrix-org/matrix-spec/issues/2240))
+- `device_one_time_keys_count` is only optional if no unclaimed one-time keys exist. ([#2245](https://github.com/matrix-org/matrix-spec/issues/2245))
+- Clarify that servers may choose not to use `M_USER_DEACTIVATED` at login time, for example for privacy reasons when they can't authenticate deactivated users. ([#2246](https://github.com/matrix-org/matrix-spec/issues/2246))
+- Usage of the `event_id_only` format for push notifications is not mandatory. ([#2255](https://github.com/matrix-org/matrix-spec/issues/2255))
+- Fix various typos throughout the specification. ([#2224](https://github.com/matrix-org/matrix-spec/issues/2224), [#2227](https://github.com/matrix-org/matrix-spec/issues/2227), [#2250](https://github.com/matrix-org/matrix-spec/issues/2250))
+
+
+## Server-Server API
+
+No significant changes.
+
+
+## Application Service API
+
+**Backwards Compatible Changes**
+
+- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
+- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
+
+**Spec Clarifications**
+
+- Fix JSON formatting in the "Server admin style permissions" examples. ([#2213](https://github.com/matrix-org/matrix-spec/issues/2213))
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- In room versions 8 through 12, clarify that "sufficient permission to invite users" on restricted joins also includes being a joined member of the room. ([#2220](https://github.com/matrix-org/matrix-spec/issues/2220))
+- In room versions 3 through 12, clarify that when you have the power to redact, it is possible to redact events that you don't have the power to send. ([#2249](https://github.com/matrix-org/matrix-spec/issues/2249))
+
+
+## Appendices
+
+No significant changes.
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Swapped icon for X (fka. twitter) to updated logo in footer. ([#2219](https://github.com/matrix-org/matrix-spec/issues/2219))
+- Inline Olm & Megolm specifications. ([#2226](https://github.com/matrix-org/matrix-spec/issues/2226), [#2241](https://github.com/matrix-org/matrix-spec/issues/2241), [#2242](https://github.com/matrix-org/matrix-spec/issues/2242))
+- Silence failing redocly-cli rule. ([#2238](https://github.com/matrix-org/matrix-spec/issues/2238))
+- Use NPM Trusted Publishers for publishing `@matrix-org/spec` to npm. ([#2239](https://github.com/matrix-org/matrix-spec/issues/2239))
+- Add version picker in the navbar. ([#2256](https://github.com/matrix-org/matrix-spec/issues/2256), [#2258](https://github.com/matrix-org/matrix-spec/issues/2258), [#2259](https://github.com/matrix-org/matrix-spec/issues/2259), [#2260](https://github.com/matrix-org/matrix-spec/issues/2260), [#2261](https://github.com/matrix-org/matrix-spec/issues/2261), [#2264](https://github.com/matrix-org/matrix-spec/issues/2264), [#2268](https://github.com/matrix-org/matrix-spec/issues/2268))
+- Add a list of endpoints to the top of each spec page. ([#2262](https://github.com/matrix-org/matrix-spec/issues/2262))

content/changelog/v1.2.md

@@ -1,23 +1,15 @@
 ---
-date: 2022-02-02T00:00:00+0000
+title: v1.2 Changelog
+linkTitle: v1.2
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2022-02-02
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.2  = Replaced by the version number (eg: v1.2)
-    February 02, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.2
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.2">https://github.com/matrix-org/matrix-doc/tree/v1.2</a></td>
-<tr><th>Release date</th><td>February 02, 2022</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
+## Client-Server API
 
 
 <strong>Breaking Changes</strong>
@@ -65,7 +57,7 @@ Variables:
 - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>New Endpoints</strong>
@@ -88,7 +80,7 @@ Variables:
 - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -99,7 +91,7 @@ Variables:
 - Correct the documentation for the response value for `GET /_matrix/app/v1/thirdparty/protocol/{protocol}`. ([#3675](https://github.com/matrix-org/matrix-doc/issues/3675))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -114,7 +106,7 @@ Variables:
 - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 <strong>Spec Clarifications</strong>
@@ -123,7 +115,7 @@ Variables:
 - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674))
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -144,7 +136,7 @@ Variables:
 - Fix auth rules to allow membership of `knock` -> `leave` in v7, v8, and v9. ([#3694](https://github.com/matrix-org/matrix-doc/issues/3694))
 
 
-### Appendices
+## Appendices
 
 
 <strong>Backwards Compatible Changes</strong>

content/changelog/v1.3.md

@@ -1,23 +1,15 @@
 ---
-date: 2022-06-15T00:00:00+0100
+title: v1.3 Changelog
+linkTitle: v1.3
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2022-06-15
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.3  = Replaced by the version number (eg: v1.2)
-    June 15, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.3
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.3">https://github.com/matrix-org/matrix-spec/tree/v1.3</a></td>
-<tr><th>Release date</th><td>June 15, 2022</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
+## Client-Server API
 
 
 <strong>Deprecations</strong>
@@ -55,7 +47,7 @@ Variables:
 - Fix membership state transitions to denote that `invite->knock` and `external->leave` are valid transitions. ([#3730](https://github.com/matrix-org/matrix-spec-proposals/issues/3730))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -79,7 +71,7 @@ Variables:
 - Clarify that the `content` for `X-Matrix` signature validation is the parsed JSON body. ([#3727](https://github.com/matrix-org/matrix-spec-proposals/issues/3727))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -88,19 +80,19 @@ Variables:
 - Add timestamp massaging as per [MSC3316](https://github.com/matrix-org/matrix-spec-proposals/pull/3316). ([#1094](https://github.com/matrix-org/matrix-spec/issues/1094))
 
 
-### Identity Service API
+## Identity Service API
 
 
 No significant changes.
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -124,7 +116,7 @@ No significant changes.
 - For room versions 7, 8, 9, and 10: fix join membership authorization rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737))
 
 
-### Appendices
+## Appendices
 
 
 No significant changes.

content/changelog/v1.4.md

@@ -1,23 +1,15 @@
 ---
-date: 2022-09-29T00:00:00+0100
+title: v1.4 Changelog
+linkTitle: v1.4
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2022-09-29
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.4  = Replaced by the version number (eg: v1.2)
-    September 29, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.4
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.4">https://github.com/matrix-org/matrix-spec/tree/v1.4</a></td>
-<tr><th>Release date</th><td>September 29, 2022</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
+## Client-Server API
 
 
 <strong>Removed Endpoints</strong>
@@ -58,7 +50,7 @@ Variables:
 - Clarify enum values by separating possible values with commas. ([#1240](https://github.com/matrix-org/matrix-spec/issues/1240))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -75,7 +67,7 @@ Variables:
 - Update "API Standards" section to clarify how JSON is used. ([#1185](https://github.com/matrix-org/matrix-spec/issues/1185))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Breaking Changes</strong>
@@ -90,7 +82,7 @@ Variables:
 - Add HTML anchors for object definitions in the formatted specification. ([#1174](https://github.com/matrix-org/matrix-spec/issues/1174))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -100,7 +92,7 @@ Variables:
 - Update "API Standards" section to clarify how JSON is used. ([#1185](https://github.com/matrix-org/matrix-spec/issues/1185))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 <strong>Spec Clarifications</strong>
@@ -109,7 +101,7 @@ Variables:
 - Add HTML anchors for object definitions in the formatted specification. ([#1174](https://github.com/matrix-org/matrix-spec/issues/1174))
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Spec Clarifications</strong>
@@ -120,13 +112,13 @@ Variables:
 - For room versions 7 through 10: Clarify that `invite->knock` is actually a legal transition. ([#1175](https://github.com/matrix-org/matrix-spec/issues/1175))
 
 
-### Appendices
+## Appendices
 
 
 No significant changes.
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 
 <strong>Backwards Compatible Changes</strong>

content/changelog/v1.5.md

@@ -1,23 +1,15 @@
 ---
-date: 2022-11-17T08:22:11-07:00
+title: v1.5 Changelog
+linkTitle: v1.5
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2022-11-17
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.5  = Replaced by the version number (eg: v1.2)
-    November 17, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.5
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.5">https://github.com/matrix-org/matrix-spec/tree/v1.5</a></td>
-<tr><th>Release date</th><td>November 17, 2022</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
+## Client-Server API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -45,7 +37,7 @@ Variables:
 - Add example read receipt to `GET /_matrix/client/v3/sync` response example. ([#1341](https://github.com/matrix-org/matrix-spec/issues/1341))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>Spec Clarifications</strong>
@@ -54,7 +46,7 @@ Variables:
 - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -63,7 +55,7 @@ Variables:
 - Clarify that application services can only register an interest in local users, as per [MSC3905](https://github.com/matrix-org/matrix-spec-proposals/issues/3905). ([#1305](https://github.com/matrix-org/matrix-spec/issues/1305))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -72,13 +64,13 @@ Variables:
 - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Spec Clarifications</strong>
@@ -89,13 +81,13 @@ No significant changes.
 - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330))
 
 
-### Appendices
+## Appendices
 
 
 No significant changes.
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 
 <strong>Backwards Compatible Changes</strong>

content/changelog/v1.6.md

@@ -1,23 +1,15 @@
 ---
-date: 2023-02-14T08:25:40-07:00
+title: v1.6 Changelog
+linkTitle: v1.6
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2023-02-14
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.6  = Replaced by the version number (eg: v1.2)
-    February 14, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.6
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.6">https://github.com/matrix-org/matrix-spec/tree/v1.6</a></td>
-<tr><th>Release date</th><td>February 14, 2023</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
+## Client-Server API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -45,7 +37,7 @@ Variables:
 - Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. ([#1433](https://github.com/matrix-org/matrix-spec/issues/1433))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>Breaking Changes</strong>
@@ -73,7 +65,7 @@ Variables:
 - Fix `edu_type` in EDU examples. ([#1383](https://github.com/matrix-org/matrix-spec/issues/1383))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -82,7 +74,7 @@ Variables:
 - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -91,7 +83,7 @@ Variables:
 - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -100,7 +92,7 @@ Variables:
 - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Backwards Compatible Changes</strong>
@@ -116,13 +108,13 @@ Variables:
 - Fix various typos throughout the specification. ([#1423](https://github.com/matrix-org/matrix-spec/issues/1423))
 
 
-### Appendices
+## Appendices
 
 
 No significant changes.
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 
 <strong>Spec Clarifications</strong>

content/changelog/v1.7.md

@@ -1,23 +1,15 @@
 ---
-date: 2023-05-25T09:47:21-06:00
+title: v1.7 Changelog
+linkTitle: v1.7
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2023-05-25
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.7  = Replaced by the version number (eg: v1.2)
-    May 25, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.7
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.7">https://github.com/matrix-org/matrix-spec/tree/v1.7</a></td>
-<tr><th>Release date</th><td>May 25, 2023</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-### Client-Server API
+## Client-Server API
 
 
 <strong>New Endpoints</strong>
@@ -63,7 +55,7 @@ Variables:
 - Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. ([#1535](https://github.com/matrix-org/matrix-spec/issues/1535))
 
 
-### Server-Server API
+## Server-Server API
 
 
 <strong>Spec Clarifications</strong>
@@ -75,7 +67,7 @@ Variables:
 - Remove extraneous `age_ts` field from the reference hash calculation section. ([#1536](https://github.com/matrix-org/matrix-spec/issues/1536))
 
 
-### Application Service API
+## Application Service API
 
 
 <strong>New Endpoints</strong>
@@ -97,7 +89,7 @@ Variables:
 - Fix various typos throughout the specification. ([#1447](https://github.com/matrix-org/matrix-spec/issues/1447))
 
 
-### Identity Service API
+## Identity Service API
 
 
 <strong>Spec Clarifications</strong>
@@ -106,13 +98,13 @@ Variables:
 - Corrections to the response format of `/_matrix/identity/v2/store-invite`. ([#1486](https://github.com/matrix-org/matrix-spec/issues/1486))
 
 
-### Push Gateway API
+## Push Gateway API
 
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 
 <strong>Spec Clarifications</strong>
@@ -121,7 +113,7 @@ No significant changes.
 - Clarifications of event ID formats in early room versions ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484))
 
 
-### Appendices
+## Appendices
 
 
 <strong>Spec Clarifications</strong>
@@ -132,7 +124,7 @@ No significant changes.
 - Clarifications of event ID formats in early room versions. ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484))
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 
 <strong>Spec Clarifications</strong>

content/changelog/v1.8.md

@@ -1,24 +1,15 @@
 ---
-date: 2023-08-23T09:23:53-06:00
+title: v1.8 Changelog
+linkTitle: v1.8
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2023-08-23
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.8  = Replaced by the version number (eg: v1.2)
-    August 23, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.8
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.8">https://github.com/matrix-org/matrix-spec/tree/v1.8</a></td>
-<tr><th>Release date</th><td>August 23, 2023</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-
-### Client-Server API
+## Client-Server API
 
 **Backwards Compatible Changes**
 
@@ -36,7 +27,7 @@ Variables:
 - Fix various typos throughout the specification. ([#1597](https://github.com/matrix-org/matrix-spec/issues/1597))
 
 
-### Server-Server API
+## Server-Server API
 
 **Deprecations**
 
@@ -58,26 +49,26 @@ Variables:
 - Switch to ordered list for server name resolution steps. ([#1623](https://github.com/matrix-org/matrix-spec/issues/1623))
 
 
-### Application Service API
+## Application Service API
 
 **Spec Clarifications**
 
 - Fix type of custom `fields` in thirdparty lookup queries. ([#1584](https://github.com/matrix-org/matrix-spec/issues/1584))
 
 
-### Identity Service API
+## Identity Service API
 
 **Spec Clarifications**
 
 - Make sure examples types match schema in definitions. ([#1563](https://github.com/matrix-org/matrix-spec/issues/1563))
 
 
-### Push Gateway API
+## Push Gateway API
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 **Backwards Compatible Changes**
 
@@ -88,7 +79,7 @@ No significant changes.
 - Update the redaction rules in room version 11, as per [MSC2176](https://github.com/matrix-org/matrix-spec-proposals/pull/2176) and [MSC3821](https://github.com/matrix-org/matrix-spec-proposals/pull/3821). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
 
 
-### Appendices
+## Appendices
 
 **Backwards Compatible Changes**
 
@@ -99,7 +90,7 @@ No significant changes.
 - Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten. ([#1573](https://github.com/matrix-org/matrix-spec/issues/1573))
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 **Backwards Compatible Changes**
 

content/changelog/v1.9.md

@@ -1,24 +1,15 @@
 ---
-date: 2023-11-29T10:04:26-07:00
+title: v1.9 Changelog
+linkTitle: v1.9
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2023-11-29
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.9  = Replaced by the version number (eg: v1.2)
-    November 29, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-## v1.9
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.9">https://github.com/matrix-org/matrix-spec/tree/v1.9</a></td>
-<tr><th>Release date</th><td>November 29, 2023</td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
-
-### Client-Server API
+## Client-Server API
 
 **Backwards Compatible Changes**
 
@@ -38,7 +29,7 @@ Variables:
 - Clarify that thread roots are not considered within the thread. ([#1677](https://github.com/matrix-org/matrix-spec/issues/1677))
 
 
-### Server-Server API
+## Server-Server API
 
 **Spec Clarifications**
 
@@ -47,27 +38,27 @@ Variables:
 - Clarify that federation requests for non-local users are invalid. ([#1672](https://github.com/matrix-org/matrix-spec/issues/1672))
 
 
-### Application Service API
+## Application Service API
 
 No significant changes.
 
 
-### Identity Service API
+## Identity Service API
 
 No significant changes.
 
 
-### Push Gateway API
+## Push Gateway API
 
 No significant changes.
 
 
-### Room Versions
+## Room Versions
 
 No significant changes.
 
 
-### Appendices
+## Appendices
 
 **Spec Clarifications**
 
@@ -75,7 +66,7 @@ No significant changes.
 - Fix various typos throughout the specification. ([#1652](https://github.com/matrix-org/matrix-spec/issues/1652))
 
 
-### Internal Changes/Tooling
+## Internal Changes/Tooling
 
 **Backwards Compatible Changes**
 

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

@@ -16,7 +16,7 @@ data with the same `type`.
 The client receives the account data as events in the `account_data`
 sections of a [`/sync`](#get_matrixclientv3sync) response.
 
-These events can also be received in a `/events` response or in the
+These events can also be received in a [`/events`](#get_matrixclientv3events) response or in the
 `account_data` section of a room in a `/sync` response. `m.tag` events appearing in
 `/events` will have a `room_id` with the room the tags are for.
 

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

@@ -16,26 +16,69 @@ 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';`.
 
-{{% boxes/added-in-paragraph %}}
-{{< 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.
-{{% /boxes/added-in-paragraph %}}
+
+{{% 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
+endpoints are expected to undergo a similar transition in a later version of the
+specification.
 
 #### Matrix Content (`mxc://`) URIs
 
 Content locations are represented as Matrix Content (`mxc://`) URIs. They
 look like:
 
+```nohighlight
 mxc://<server-name>/<media-id>
 
 <server-name> : The name of the homeserver where this content originated, e.g. matrix.org
 <media-id> : An opaque ID which identifies the content.
+```
 
-#### Client behaviour
+#### Client behaviour {id="content-repo-client-behaviour"}
 
-Clients can upload and download content using the following HTTP APIs.
+Clients can access the content repository using the following endpoints.
+
+{{% 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.
+
+{{% boxes/warning %}}
+By Matrix 1.12, servers SHOULD "freeze" the deprecated, unauthenticated, endpoints
+to prevent newly-uploaded media from being downloaded. This SHOULD mean that any
+media uploaded *before* the freeze remains accessible via the deprecated endpoints,
+and any media uploaded *after* (or *during*) the freeze SHOULD only be accessible
+through the new, authenticated, endpoints. For remote media, "newly-uploaded" is
+determined by the date the cache was populated. This may mean the media is older
+than the freeze, but because the server had to re-download it, it is now considered
+"new".
+
+Clients SHOULD update to support the authenticated endpoints before servers freeze
+unauthenticated access.
+
+Servers SHOULD consider their local ecosystem impact before enacting a freeze.
+This could mean ensuring their users' typical clients support the new endpoints
+when available, or updating bridges to start using media proxies.
+
+In addition to the above, servers SHOULD exclude [IdP icons used in the `m.login.sso` flow](/client-server-api/#definition-mloginsso-flow-schema)
+from the freeze. See the `m.login.sso` flow schema for details.
+
+An *example* timeline for a server may be:
+
+* Matrix 1.11 release: Clients begin supporting authenticated media.
+* Matrix 1.12 release: Servers freeze unauthenticated media access.
+  * Media uploaded prior to this point still works with the deprecated endpoints.
+  * Newly uploaded (or cached) media *only* works on the authenticated endpoints.
+
+Matrix 1.12 is expected to be released in the July-September 2024 calendar quarter.
+{{% /boxes/warning %}}
+
+{{% http-api spec="client-server" api="authed-content-repo" %}}
 
 {{% http-api spec="client-server" api="content-repo" %}}
 
@@ -44,7 +87,7 @@ Clients can upload and download content using the following HTTP APIs.
 The homeserver SHOULD be able to supply thumbnails for uploaded images
 and videos. The exact file types which can be thumbnailed are not
 currently specified - see [Issue
-\#1938](https://github.com/matrix-org/matrix-doc/issues/1938) for more
+\#1938](https://github.com/matrix-org/matrix-spec/issues/453) for more
 information.
 
 The thumbnail methods are "crop" and "scale". "scale" tries to return an
@@ -91,9 +134,14 @@ entity isn't in the room.
 `mxc://` URIs are vulnerable to directory traversal attacks such as
 `mxc://127.0.0.1/../../../some_service/etc/passwd`. This would cause the
 target homeserver to try to access and return this file. As such,
-homeservers MUST sanitise `mxc://` URIs by allowing only alphanumeric
-(`A-Za-z0-9`), `_` and `-` characters in the `server-name` and
-`media-id` values. This set of whitelisted characters allows URL-safe
+homeservers MUST sanitise `mxc://` URIs by:
+
+-   restricting the `server-name` segment to valid
+    [server names](/appendices/#server-name)
+-   allowing only alphanumeric (`A-Za-z0-9`), `_` and `-` characters in
+    the `media-id` segment
+
+The resulting set of whitelisted characters allows URL-safe
 base64 encodings specified in RFC 4648. Applying this character
 whitelist is preferable to blacklisting `.` and `/` as there are
 techniques around blacklisted characters (percent-encoded characters,
@@ -119,3 +167,50 @@ Homeservers have additional content-specific concerns:
 -   Clients or remote homeservers may try to upload malicious files
     targeting vulnerabilities in either the homeserver thumbnailing or
     the client decoders.
+
+##### Serving inline content
+
+Clients with insecure configurations may be vulnerable to Cross-Site Scripting
+attacks when served media with a `Content-Disposition` of `inline`. Clients
+SHOULD NOT be hosted on the same domain as the media endpoints for the homeserver
+to mitigate most of this risk. Servers SHOULD restrict `Content-Type` headers to
+one of the following values when serving content with `Content-Disposition: inline`:
+
+* `text/css`
+* `text/plain`
+* `text/csv`
+* `application/json`
+* `application/ld+json`
+* `image/jpeg`
+* `image/gif`
+* `image/png`
+* `image/apng`
+* `image/webp`
+* `image/avif`
+* `video/mp4`
+* `video/webm`
+* `video/ogg`
+* `video/quicktime`
+* `audio/mp4`
+* `audio/webm`
+* `audio/aac`
+* `audio/mpeg`
+* `audio/ogg`
+* `audio/wave`
+* `audio/wav`
+* `audio/x-wav`
+* `audio/x-pn-wav`
+* `audio/flac`
+* `audio/x-flac`
+
+These types are unlikely to cause Cross-Site Scripting issues when a `Content-Type`
+header is provided, as clients will only try to render the data using that content
+type. For example, if a HTML file is uploaded with a `Content-Type` of `image/png`,
+clients will just assume that the image is corrupted, and won't render it as a
+HTML page. Therefore, there is no risk in trusting the user-defined content type,
+as long as the `Content-Disposition` is calculated based on that type.
+
+Clients SHOULD NOT rely on servers returning `inline` rather than `attachment`
+on [`/download`](#get_matrixclientv1mediadownloadservernamemediaid). Server implementations might decide out of an abundance of
+caution that all downloads are responded to with `attachment`, regardless of
+content type - clients should not be surprised by this behaviour.