Spec for MSC4230: Flag for animated images (#2328)

* Spec for MSC4230: Flag for animated images

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

* Add changelog

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

* Add x-addedInMatrixVersion property

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

---------

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

.github/ISSUE_TEMPLATE/release.md

@@ -0,0 +1,37 @@
+---
+name: '[SCT] Release checklist'
+about: 'Used by the Spec Core Team to create a new release.'
+title: 'Matrix 1.X'
+labels: 'release-blocker'
+assignees: ''
+
+---
+
+<!-- ------------------------------------------------------------------------ -->
+<!-- Please asssign the release coordinator (probably yourself) to this issue -->
+<!-- ------------------------------------------------------------------------ -->
+
+Date: **Thursday, May 25, 2023** <!-- CHANGE ME -->
+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.
+
+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.
+* [ ] 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/checks.yaml

@@ -10,7 +10,7 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - run: scripts/check-newsfragments

.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:
@@ -18,32 +24,71 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
-      - name: "⚙️ npm"
-        working-directory: "./scripts"
-        run: |
-          npm install
+          node-version: ${{ env.NODE_VERSION }}
       - name: "🔎 Run validator"
-        working-directory: "./scripts"
         run: |
-          node validator.js -s "../data/api/application-service"
-          node validator.js -s "../data/api/client-server"
-          node validator.js -s "../data/api/push-gateway"
+          npx @redocly/cli@latest lint data/api/*/*.yaml
 
-  check-examples:
+  check-event-examples:
     name: "🔎 Check Event schema examples"
     runs-on: ubuntu-latest
-    container: uhoreg/matrix-doc-build
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
       - name: "🔎 Run validator"
         run: |
-          /env/bin/python scripts/check-event-schema-examples.py
+          python scripts/check-event-schema-examples.py
+
+  check-openapi-examples:
+    name: "🔎 Check OpenAPI definitions examples"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
+      - name: "🔎 Run validator"
+        run: |
+          python scripts/check-openapi-sources.py
+
+  check-schemas-examples:
+    name: "🔎 Check JSON Schemas inline examples"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
+      - name: "🔎 Run validator"
+        run: |
+          python scripts/check-json-schemas.py
 
   calculate-baseurl:
     name: "⚙️ Calculate baseURL for later jobs"
@@ -60,131 +105,259 @@ 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:
     name: "🐍 Build OpenAPI definitions"
     runs-on: ubuntu-latest
-    container: "python:3.9"
     needs: [calculate-baseurl]
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
       - name: "📦 Asset creation"
         run: |
-          python3 -m venv env && . env/bin/activate
-          pip install -r scripts/requirements.txt
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            export RELEASE="${GITHUB_REF/refs\/tags\//}"
+          else
+            export RELEASE="unstable"
+          fi
           # The output path matches the final deployment path at spec.matrix.org
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api application-service \
+            -r "$RELEASE" \
             -o spec/application-service-api/api.json
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api client-server \
+            -r "$RELEASE" \
             -o spec/client-server-api/api.json
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api push-gateway \
+            -r "$RELEASE" \
             -o spec/push-gateway-api/api.json
+          scripts/dump-openapi.py \
+              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
+              --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@v2
+        uses: actions/upload-artifact@v4
         with:
           name: openapi-artifact
           path: openapi.tar.gz
 
+  generate-changelog:
+    name: "📢 Run towncrier for changelog"
+    # skip for builds of git tags
+    if: "!startsWith(github.ref, 'refs/tags/')"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        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@v4
+        with:
+          name: changelog-artifact
+          path: content/changelog/unstable.md
+
   build-spec:
     name: "📖 Build the spec"
     runs-on: ubuntu-latest
-    needs: [calculate-baseurl, build-openapi]
+    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@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: ${{ env.NODE_VERSION }}
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.93.3'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
-        with:
-          submodules: 'recursive'
+        uses: actions/checkout@v4
       - name: "⚙️ npm"
         run: |
           npm i
           npm run get-proposals
+      - name: "📥 Download generated changelog"
+        if: "needs.generate-changelog.result == 'success'"
+        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@v2
+        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@v2
+        uses: actions/upload-artifact@v4
         with:
           name: spec-artifact
           path: spec.tar.gz
 
+  htmlcheck:
+    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@v4
+        with:
+          name: spec-artifact
+
+      - name: "📝 Unpack the spec"
+        run: |
+          mkdir spec
+          tar -C spec -xvzf spec.tar.gz
+
+      - name: "Run htmltest"
+        uses: wjdp/htmltest-action@master
+        with:
+          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@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: ${{ env.NODE_VERSION }}
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.93.3'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
-        with:
-          submodules: 'recursive'
+        uses: actions/checkout@v4
       - name: "⚙️ npm"
         run: |
           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@v2
+        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@v2
+        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@af92a8455a59214b7b932932f2662fdefbd78126 # v2.15.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
-        # v1.2.2
-        uses: nwtgck/actions-netlify@f517512ae75beec8896aa7b027c1c72f01816200
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
         with:
           publish-dir: spec
           deploy-message: "Deploy from GitHub Actions"

.github/workflows/release.yaml

@@ -0,0 +1,43 @@
+name: Release packages
+on:
+  release:
+    types: [published]
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+jobs:
+  # Releases to npm after bumping the package.json version from 0.0.0 to $TAG.0 as the tags only contain MAJOR.MINOR
+  npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    if: github.event.release.prerelease == false
+    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@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#v} --no-git-tag-version"
+        env:
+          VERSION: ${{ github.event.release.tag_name }}.0
+
+      - name: 🚀 Publish to npm
+        run: npm publish --provenance --access public --tag latest

.github/workflows/spell-check.yaml

@@ -11,9 +11,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout Actions Repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Check spelling of proposals
-      uses: crate-ci/typos@9be36f97fdbe645ee9a12449fb13aca856c2516a
+      uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10
       with:
         config: ${{github.workspace}}/.github/_typos.toml

.gitignore

@@ -2,7 +2,7 @@ node_modules
 /data/msc
 /env*
 /resources
-/scripts/swagger
+/scripts/openapi
 /scripts/tmp
 /hugo-config.toml
 /public
@@ -14,3 +14,4 @@ _rendered.rst
 /spec/
 changelogs/rendered.*
 .hugo_build.lock
+hugo_stats.json

.gitmodules

@@ -1,4 +0,0 @@
-[submodule "themes/docsy"]
-	path = themes/docsy
-	url = https://github.com/matrix-org/docsy.git
-	branch = master

.htmltest.yml

@@ -0,0 +1,7 @@
+# config file for htmltest. This is used by one of the checks in Github
+# Actions.
+
+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
 ~~~~~~~~~~~~~~~~~~~~~
@@ -72,12 +72,16 @@ ask.
 Adding to the changelog
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-All API specifications require a changelog entry. Adding to the changelog can only
+All changes to the contents of this repository require a changelog entry. Adding to the changelog can only
 be done after you've opened your pull request, so be sure to do that first.
 
 The changelog is managed by `Towncrier <https://github.com/twisted/towncrier>`_ in the
-form of "news fragments". The news fragments for the client-server API are stored
-under ``changelogs/client_server/newsfragments``.
+form of "news fragments". Depending on which API you changed, an entry should be added to
+each relevant API's ``newsfragments`` directory. A directory exists for each API under
+``changelogs/``. For instance, news fragments for the client-server API are stored
+under ``changelogs/client_server/newsfragments``. Any changes to the repository that do
+not affect the spec content itself, such as changes to the build script, formatting, CSS,
+etc. should be documented under ``changelogs/internal/newsfragments``.
 
 To create a changelog entry, create a file named in the format ``prNumber.type`` in
 the ``newsfragments`` directory. The ``type`` can be one of the following:
@@ -95,13 +99,12 @@ 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.
 
-Changes that do not change the spec, such as changes to the build script, formatting,
-CSS, etc should not get a news fragment.
-
 Sign off
 --------
 
@@ -116,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::
@@ -162,7 +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 :)
+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

@@ -1,6 +1,6 @@
 # Matrix Specification
 
-This repository contains the Matrix Specification, rendered at [spec.matrix.org](http://spec.matrix.org/).
+This repository contains the Matrix Specification. The current release version is rendered at https://spec.matrix.org, while the latest available build of the `main` branch is at https://spec.matrix.org/unstable.
 
 Developers looking to use Matrix should join [#matrix-dev:matrix.org](https://matrix.to/#/#matrix-dev:matrix.org)
 on Matrix for help.
@@ -22,7 +22,7 @@ The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site gener
 
 * `/data`: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as
   [data objects](https://gohugo.io/templates/data-templates/), so templates don't need to load them from a file and
-  parse them. This is also where our Swagger/OpenAPI definitions and schemas are.
+  parse them. This is also where our OpenAPI definitions and schemas are.
 
 * `/layouts`: this contains [Hugo templates](https://gohugo.io/templates/). Some templates define the overall layout of
   a page: for example, whether it has header, footer, sidebar, and so on.
@@ -52,6 +52,7 @@ Additionally, the following directories may be of interest:
 * `/data-definitions`: Bits of structured data consumable by Matrix implementations.
 * `/meta`: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc).
 * `/scripts`: Various scripts for generating the spec and validating its contents.
+* `/packages`: Various packages for shipping spec files like OpenAPI bindings and data definitions.
 
 ## Authoring changes to the spec
 
@@ -60,20 +61,19 @@ 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.93.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
    to process the SCSS.)
-2. Run `git submodule update --init --recursive` for good measure.
-3. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
-4. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
+2. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
+3. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
    page and is not required.
-5. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313
+4. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313
    klakegg/hugo:ext serve`) to run a local webserver which builds whenever a file
    change is detected. If watching doesn't appear to be working for you, try
    adding `--disableFastRender` to the commandline.
-6. Edit the specification 🙂
+5. Edit the specification 🙂
 
 We use a highly customized [Docsy](https://www.docsy.dev/) theme for our generated site, which uses Bootstrap and Font
 Awesome. If you're looking at making design-related changes to the spec site, please coordinate with us in
@@ -86,15 +86,13 @@ steps for authoring changes to the specification and instead of `hugo serve` run
 spec to `/spec`. If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"`
 to the `hugo -d "spec"` command.
 
-For building the swagger definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
-and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file,
+For building the OpenAPI definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
+and finally `python ./scripts/dump-openapi.py` to generate it to `./scripts/openapi/api-docs.json`. To make use of the generated file,
 there are a number of options:
 
-* It can be uploaded from your filesystem to an online editor/viewer such as [on the swagger website](http://editor.swagger.io/).
-* You can run a local HTTP server by running `./scripts/swagger-http-server.py`, and then view the documentation via an
-  online viewer; for example, at <http://petstore.swagger.io/?url=http://localhost:8000/api-docs.json>.
-* You can host the swagger UI yourself. See <https://github.com/swagger-api/swagger-ui#how-to-run> for advice on how to
-  do so.
+* You can open `./scripts/openapi-preview.html` in your browser, and then open the file by clicking on `Local JSON File`.
+* You can run a local HTTP server by running `./scripts/openapi-http-server.py`, and then view the documentation by
+  opening `./scripts/openapi-preview.html` in your browser.
 
 ## Issue tracking
 

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

@@ -0,0 +1,663 @@
+/*
+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.
+*/
+
+/*
+Custom SCSS for the Matrix spec
+*/
+
+/* Import the CSS classes for the syntax highlighter.
+ *
+ * This is generated with:
+ *
+ *    hugo gen chromastyles --style=tango > assets/scss/syntax.scss
+ */
+@import "syntax.scss";
+
+/* Overrides for the navbar */
+.td-navbar {
+  box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
+  min-height: 5rem;
+
+  .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 {
+    font-weight: normal;
+  }
+
+  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 */
+.td-sidebar {
+    /* don't attempt to use the sidebar (or things in it) as a scroll anchor. */
+    overflow-anchor: none;
+}
+
+.td-sidebar-nav {
+  scroll-behavior: smooth;
+  overscroll-behavior: contain;
+
+  & > .td-sidebar-nav__section {
+    margin-top: 1rem;
+
+    .ul-1 ul {
+      padding-left: 0;
+    }
+
+    /* This is to make the width of the items that have sub-items (like room versions)
+    the same as the width of items that don't (like changelog) */
+    .pr-md-3, .px-md-3 {
+      padding-right: 0 !important;
+    }
+
+    .ul-1 > li > a {
+      padding-left: 1rem !important;
+    }
+
+    .ul-2 > li > a {
+      padding-left: 2rem !important;
+    }
+  }
+
+  /* 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;
+      margin-bottom: 0;
+      border-bottom: none;
+    }
+
+    li a, li a.td-sidebar-link {
+      color: $gray-800;
+      font-weight: $font-weight-normal;
+      padding-top: .2rem;
+      padding-bottom: .2rem;
+
+      transition: all 100ms ease-in-out;
+
+      &:hover {
+        background-color: $secondary-lighter-background;
+        color: $gray-800;
+      }
+
+      &.active, &active:hover {
+        background-color: $secondary-background;
+      }
+    }
+  }
+}
+
+@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 */
+      max-height: calc(100vh - 6rem);
+    }
+  }
+}
+
+/* Customise 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 */
+.td-content {
+
+  counter-reset: h2;
+
+  &> h2 {
+    counter-reset: h3
+  }
+
+  &> h3 {
+    counter-reset: h4
+  }
+
+  &> h4 {
+    counter-reset: h5
+  }
+
+  &> h5 {
+    counter-reset: h6
+  }
+
+  &> h2:not(.no-numbers):before {
+    display: inline; visibility: visible; counter-increment: h2; content: counter(h2) ". "
+  }
+
+  &> h3:not(.no-numbers):before {
+    display: inline; visibility: visible; counter-increment: h3; content: counter(h2) "." counter(h3) ". "
+  }
+
+  &> h4:not(.no-numbers):before {
+    display: inline; visibility: visible; counter-increment: h4; content: counter(h2) "." counter(h3) "." counter(h4) ". "
+  }
+
+  &> h5:not(.no-numbers):before {
+    display: inline; visibility: visible; counter-increment: h5; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". "
+  }
+
+  &> h6:not(.no-numbers):before {
+    display: inline; visibility: visible; counter-increment: h6; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". "
+  }
+
+}
+
+/* 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;
+}
+
+.endpoints-toc {
+  summary {
+    cursor: pointer;
+    font-weight: $font-weight-bold;
+    font-size: 1.05rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .endpoint-list {
+    list-style: none;
+    padding-left: 0;
+    margin: 0;
+  }
+
+  .endpoint-list li {
+    margin: 0.2rem 0;
+  }
+
+  .endpoint-list a {
+    text-decoration: none;
+    color: inherit;
+    padding: 0.05rem 0.25rem;
+    border-radius: 0.2rem;
+
+    &:hover {
+      background-color: $secondary-background;
+    }
+  }
+
+  .endpoint-list .http-api-method {
+    margin-right: 0.35rem;
+    font-weight: $font-weight-bold;
+  }
+
+  .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 */
+.alert {
+  &.note {
+    &:not(.omit-title):before {
+      content: "INFO: ";
+      font-weight: $font-weight-bold;
+    }
+    border: 2px solid $note;
+    border-left-width: 5px;
+    background: $note-background;
+  }
+
+  &.rationale {
+    &:not(.omit-title):before {
+      content: "RATIONALE: ";
+      font-weight: $font-weight-bold;
+    }
+    border: 2px solid $note;
+    border-left-width: 5px;
+    background: $note-background;
+  }
+
+  &.warning {
+    &:not(.omit-title):before {
+      content: "WARNING: ";
+      font-weight: $font-weight-bold;
+    }
+    border: 2px solid $warning;
+    border-left-width: 5px;
+    background: $warning-background;
+  }
+}
+
+/* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
+.td-content .rendered-data {
+  background-color: $secondary-lightest-background;
+  padding: 0.85rem;
+  margin: 0.85rem 0;
+
+  details {
+    summary {
+      h1 {
+        margin: 0;
+        /* Ensure the disclosure control is vertically centred with the header text. */
+        vertical-align: middle;
+      }
+    }
+    p {
+      max-width: 80%;
+    }
+  }
+
+  .deprecated-inline {
+
+    &:after {
+      content: " — DEPRECATED";
+      color: $warning;
+      font-weight: $font-weight-bold;
+    }
+  }
+
+  h1 {
+    display: inline-block;
+    font-size: 1.3rem;
+
+    .endpoint {
+      color: $secondary;
+    }
+  }
+
+  h2 {
+    font-weight: $font-weight-bold;
+    font-size: 1.3rem;
+    margin: 1.5rem 0 1rem 0;
+  }
+
+  h3 {
+    font-weight: $font-weight-bold;
+    font-size: 1.1rem;
+    margin: 1.5rem 0 1rem 0;
+
+  }
+
+  /* Reduce top margin of h3 if previous sibling is a h2 */
+  h2 + h3 {
+    margin-top: 1rem;
+  }
+
+  hr {
+    border-bottom: 2px solid $dark;
+    margin-bottom: 1.5rem;
+  }
+
+  p code, table code {
+    background-color: transparent;
+  }
+
+  table {
+    @media (max-width: 800px) {
+      /* Docsy by default applies `overflow-x: auto;` to tables, which
+       * results in annoying horizontal scrolling on mobile, so we instead
+       * switch to a fixed table layout on a narrow browser width.
+       * (On a wider width the default auto table-layout provides better readability.)
+       *
+       * Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create
+       * tables with a "display" property of "block".
+       * However, for "table-layout: fixed" to be effective, an element must have a
+       * "display" property of "table".
+       *
+       * Thus, we override the "display" property here. This may no longer be necessary once
+       * Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470.
+       * For more details, see
+       * https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */
+      display: table;
+      table-layout: fixed;
+      width: 100%;
+
+      .col-name, .col-type, .col-status {
+        width: 25%;
+      }
+
+      .col-description {
+        width: 50%;
+      }
+
+      .col-status-description {
+        width: 75%;
+      }
+    }
+
+    caption {
+      caption-side: top;
+      color: $dark;
+      font-size: 1rem;
+      font-weight: $font-weight-bold;
+    }
+
+    th, td, caption {
+      padding: 1rem;
+      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;
+
+        caption {
+            // the caption is outside the table's border box,
+            // so we have to give it its own border.
+            border: 1px $table-border-color solid;
+
+            // ... but avoid double border between caption and table
+            border-bottom: 0;
+
+            background-color: $secondary-lighter-background;
+        }
+
+        tbody tr {
+            --bs-table-striped-bg: #{$secondary-lighter-background};
+        }
+    }
+
+    &.basic-info, &.basic-info th, &.basic-info td {
+      table-layout: fixed;
+      margin: 1rem 0 .5rem 0;
+    }
+
+    &.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 {
+    border: 0;
+    border-left: solid 5px $secondary;
+  }
+
+  .http-api-method {
+    font-weight: $font-weight-bold;
+  }
+
+}
+
+/* Miscellaneous custom bits */
+
+/* Update link colours for MAtrix style */
+a, a:hover {
+  color: $secondary;
+}
+
+/* This is needed to stop the bottom of the Matrix icon from getting snipped off. */
+.td-navbar .navbar-brand svg {
+  height: 32px;
+}
+
+/* Give code samples and pre elements full-width */
+.td-content > .highlight, .td-content > pre {
+  max-width: 100%;
+}
+
+/* The default CSS applies a style for blockquotes but only to immediate children
+of .td-content. This applies the same style to any blockquotes that descend from
+.td-content. */
+.td-content blockquote {
+  padding: 0 0 0 1rem;
+  margin-bottom: $spacer;
+  color: $gray-600;
+  border-left: 6px solid $secondary;
+}
+
+/*
+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;
+  background-color: $gray-100;
+}
+
+.pageinfo-unstable {
+  background-image: url('../icons/unstable.png');
+  background-position: left 1rem center;
+  background-repeat: no-repeat;
+  padding-left: 100px;
+}
+
+/* Adjust the styling of definition lists. */
+
+/* Add a little spacing between the term and its definition. */
+dt {
+   margin-bottom: 0.15rem;
+}
+
+/* _reboot.scss deliberately sets margin-left to 0. Undo this. */
+dd {
+  margin-left: 2rem;
+}
+
+/* docsy's _code.scss does only styles <code> elements matching
+ * .td-content { p code, li > code, table code }.
+ * Copy those styles here to apply to code <elements> in definition terms too. */
+
+.td-content {
+  dt code {
+    color: inherit;
+    padding: 0.2em 0.4em;
+    margin: 0;
+    font-size: 85%;
+    word-break: normal;
+    background-color: rgba($black, 0.05);
+    border-radius: 0.25rem;  // was $border-radius, but that var isn't accessible here.
+  }
+}
+
+/* Style for breadcrumbs */
+.td-breadcrumbs {
+  padding: .75rem 1rem;
+  background-color: #eee;
+  border-radius: .25rem;
+  margin-bottom: 1rem;
+
+  .breadcrumb {
+    margin: 0;
+  }
+}

assets/scss/_variables_project.scss

@@ -18,9 +18,10 @@ $primary: #FFF;
 $secondary: #0098D4;
 $dark: #333;
 $gray-100: #FBFBFB;
+$code-color: #005b7f;
 
 $secondary-background: #E5F5FB;
-$secondary-lighter-background: #F4FaFC;
+$secondary-lighter-background: #F4FAFC;
 $secondary-lightest-background: #FBFDFD;
 
 
@@ -33,12 +34,24 @@ $warning-background: #FFE0E0;
 // colours for definition tables.
 // the border colour matches that used for "highlight" divs
 $table-border-color: rgba(black, .125);
-$table-row-alternate: $secondary-lightest-background;
-$table-row-default: $secondary-lighter-background;
+$table-bg: $secondary-lightest-background;
+
+/* Configure docsy to use the default system fonts instead of Google Fonts.
+ * See https://www.docsy.dev/docs/adding-content/lookandfeel/#fonts */
+$td-enable-google-fonts: false;
 
 /*
- Opt to serve fonts locally by overriding web-font-path to be a non-google fonts URL.
- This is only possible with our modified docsy theme: https://github.com/matrix-org/docsy
+ * 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)
  */
-$web-font-path: "../css/fonts/Inter.css";
-$google_font_name: "Inter";
+$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;

assets/scss/custom.scss

@@ -1,471 +0,0 @@
-/*
-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.
-*/
-
-/*
-Custom SCSS for the Matrix spec
-*/
-
-@import "variables_project";
-@import "variables";
-
-/* Import the CSS classes for the syntax highlighter.
- *
- * This is generated with:
- *
- *    hugo gen chromastyles --style=tango > assets/scss/syntax.scss
- */
-@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);
-  min-height: 5rem;
-
-  .navbar-brand {
-    font-size: 1.1rem;
-
-    .navbar-version {
-      color: $secondary;
-    }
-
-  }
-
-  a {
-    color: $black;
-  }
-}
-
-/* Styles for the sidebar nav */
-.td-sidebar {
-    /* don't attempt to use the sidebar (or things in it) as a scroll anchor. */
-    overflow-anchor: none;
-}
-
-.td-sidebar-nav {
-  scroll-behavior: smooth;
-  overscroll-behavior: contain;
-
-  &>.td-sidebar-nav__section {
-    margin-top: 1rem;
-  }
-
-  &>.td-sidebar-nav__section > li > a.td-sidebar-link {
-      font-weight: $font-weight-bold;
-      font-size: 1.3rem;
-  }
-
-  /* This is to make the width of the items that have sub-items (like room versions)
-  the same as the width of items that don't (like changelog) */
-  .pr-md-3, .px-md-3 {
-    padding-right: 0 !important;
-  }
-
-  a.indent-1 {
-    padding-left: 1rem !important;
-  }
-
-  a.indent-2 {
-    padding-left: 2rem;
-  }
-
-  a, 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 {
-      background-color: $secondary-lighter-background;
-      color: $gray-800;
-    }
-
-    &.active, &active:hover {
-      background-color: $secondary-background;
-      font-weight: $font-weight-normal;
-    }
-  }
-}
-
-@media (min-width: 768px) {
-  @supports (position: sticky) {
-    .td-sidebar-nav {
-      /* This overrides calc(100vh - 10rem);, which gives us a blank space at the bottom of the sidebar */
-      max-height: calc(100vh - 6rem);
-    }
-  }
-}
-
-/* Customise footer */
-footer {
-  box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
-}
-
-/* Auto numbering for headings */
-.td-content {
-
-  counter-reset: h2;
-
-  &> h2 {
-    counter-reset: h3
-  }
-
-  &> h3 {
-    counter-reset: h4
-  }
-
-  &> h4 {
-    counter-reset: h5
-  }
-
-  &> h5 {
-    counter-reset: h6
-  }
-
-  &> h2:not(.no-numbers):before {
-    display: inline; visibility: visible; counter-increment: h2; content: counter(h2) ". "
-  }
-
-  &> h3:not(.no-numbers):before {
-    display: inline; visibility: visible; counter-increment: h3; content: counter(h2) "." counter(h3) ". "
-  }
-
-  &> h4:not(.no-numbers):before {
-    display: inline; visibility: visible; counter-increment: h4; content: counter(h2) "." counter(h3) "." counter(h4) ". "
-  }
-
-  &> h5:not(.no-numbers):before {
-    display: inline; visibility: visible; counter-increment: h5; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". "
-  }
-
-  &> h6:not(.no-numbers):before {
-    display: inline; visibility: visible; counter-increment: h6; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". "
-  }
-
-}
-
-/* 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 {
-        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, ".") " ";
-  }
-
-  #toc-title {
-    font-weight: $font-weight-bold;
-    font-size: 1.3rem;
-  }
-
-}
-
-/* Styles for alert boxes */
-.alert {
-  &.note {
-    &:not(.omit-title):before {
-      content: "INFO: ";
-      font-weight: $font-weight-bold;
-    }
-    border: 2px solid $note;
-    border-left-width: 5px;
-    background: $note-background;
-  }
-
-  &.rationale {
-    &:not(.omit-title):before {
-      content: "RATIONALE: ";
-      font-weight: $font-weight-bold;
-    }
-    border: 2px solid $note;
-    border-left-width: 5px;
-    background: $note-background;
-  }
-
-  &.warning {
-    &:not(.omit-title):before {
-      content: "WARNING: ";
-      font-weight: $font-weight-bold;
-    }
-    border: 2px solid $warning;
-    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 */
-.rendered-data {
-  background-color: $secondary-lightest-background;
-  padding: 1rem;
-  margin: 1rem 0;
-
-  details {
-    summary {
-      padding: .5rem 0;
-      p {
-        max-width: 80%;
-      }
-    }
-  }
-
-  .deprecated-inline {
-
-    &:after {
-      content: " — DEPRECATED";
-      color: $warning;
-      font-weight: $font-weight-bold;
-    }
-  }
-
-  h1 {
-    display: inline-block;
-    font-size: 1.3rem;
-
-    .endpoint {
-      color: $secondary;
-    }
-  }
-
-  h2 {
-    font-weight: $font-weight-bold;
-    font-size: 1.3rem;
-    margin: 3rem 0 .5rem 0;
-  }
-
-  h3 {
-    font-weight: $font-weight-bold;
-    font-size: 1.1rem;
-    margin: 1.5rem 0 .75rem 0;
-  }
-
-  hr {
-    border-bottom: 2px solid $dark;
-    margin-bottom: 1.5rem;
-  }
-
-  p code, table code {
-    background-color: inherit;
-  }
-
-  table {
-    table-layout: fixed;
-    width: 100%;
-
-    // add some space between two tables when they are right next to each other
-    & + table {
-        margin-top: 4rem;
-    }
-
-    caption {
-      caption-side: top;
-      color: $dark;
-      font-size: 1rem;
-      font-weight: $font-weight-bold;
-    }
-
-    th, td, caption {
-      padding: 1rem;
-    }
-
-    &.object-table, &.response-table {
-        border: 1px $table-border-color solid;
-
-        caption {
-            // the caption is outside the table's border box,
-            // so we have to give it its own border.
-            border: 1px $table-border-color solid;
-
-            // ... but avoid double border between caption and table
-            border-bottom: 0;
-        }
-
-        caption, tbody tr {
-            background-color: $table-row-default;
-        }
-
-        tbody tr:nth-child(even) {
-            background-color: $table-row-alternate;
-        }
-    }
-
-    &.basic-info, &.basic-info th, &.basic-info td {
-      table-layout: fixed;
-      margin: 1rem 0 .5rem 0;
-    }
-
-    &.basic-info th {
-      width: 15rem;
-    }
-
-    .col-name, .col-type, .col-status {
-      width: 25%;
-    }
-
-    .col-description {
-      width: 50%;
-    }
-
-    .col-status-description {
-      width: 75%;
-    }
-
-  }
-
-  pre {
-    border: 0;
-    border-left: solid 5px $secondary;
-  }
-
-  .http-api-method {
-    font-weight: $font-weight-bold;
-  }
-
-}
-
-/* Miscellaneous custom bits */
-
-/* Update link colours for MAtrix style */
-a, a:hover {
-  color: $secondary;
-}
-
-/* This is needed to stop the bottom of the Matrix icon from getting snipped off. */
-.td-navbar .navbar-brand svg {
-  height: 32px;
-}
-
-/* Give code samples and pre elements full-width */
-.td-content > .highlight, .td-content > pre {
-  max-width: 100%;
-}
-
-/* The default CSS applies a style for blockquotes but only to immediate children
-of .td-content. This applies the same style to any blockquotes that descend from
-.td-content. */
-.td-content blockquote {
-  padding: 0 0 0 1rem;
-  margin-bottom: $spacer;
-  color: $gray-600;
-  border-left: 6px solid $secondary;
-}
-
-/*
-Make padding symmetrical (this selector is used in the default styles to apply padding-left: 3rem)
-*/
-.pl-md-5, .px-md-5 {
-  padding-right: 3rem;
-}
-
-/* Adjust default styles for info banner */
-.pageinfo-primary {
-  max-width: 80%;
-  margin-left: 0;
-  border: 0;
-  border-left: solid 5px $secondary;
-  background-color: $gray-100;
-}
-
-.pageinfo-unstable {
-  background-image: url('../icons/unstable.png');
-  background-position: left 1rem center;
-  background-repeat: no-repeat;
-  padding-left: 100px;
-}
-
-/* Full-width tables */
-.td-content > table {
-  width: 100%;
-  display: table;
-}

attic/drafts/model/rooms.rst

@@ -246,7 +246,7 @@ anyway.
 In this arrangement there is now a room with both users may join but neither has
 the power to invite any others. Both users now have the confidence that (at
 least within the messaging system itself) their messages remain private and
-cannot later be provably leaked to a third party. They can freely set the topic
+cannot later be provably leaked to a third-party. They can freely set the topic
 or name if they choose and add or edit any other state of the room. The update
 powerlevel of each of these fixed properties should be 1, to lock out the users
 from being able to alter them.

attic/drafts/model/third-party-id.rst

@@ -1,9 +1,9 @@
 ======================
-Third Party Identities
+Third-party Identities
 ======================
 
-A description of how email addresses, mobile phone numbers and other third
-party identifiers can be used to authenticate and discover users in Matrix.
+A description of how email addresses, mobile phone numbers and other third-party
+identifiers can be used to authenticate and discover users in Matrix.
 
 
 Overview
@@ -15,16 +15,16 @@ and phone numbers for contacts in their address book. They want to communicate
 with those contacts in Matrix without manually exchanging a Matrix User ID with 
 them.
 
-Third Party IDs
+Third-party IDs
 ---------------
 
 [[TODO(markjh): Describe the format of a 3PID]]
 
 
-Third Party ID Associations
+Third-party ID Associations
 ---------------------------
 
-An Associaton is a binding between a Matrix User ID and a Third Party ID (3PID).
+An Associaton is a binding between a Matrix User ID and a Third-party ID (3PID).
 Each 3PID can be associated with one Matrix User ID at a time.
 
 [[TODO(markjh): JSON format of the association.]]

changelogs/appendices/newsfragments/2307.clarification

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

changelogs/application_service/newsfragments/1174.clarification

@@ -1 +0,0 @@
-Add HTML anchors for object definitions in the formatted specification.

changelogs/application_service/newsfragments/1200.breaking

@@ -1 +0,0 @@
-Replace homeserver authorization approach with an `Authorization` header instead of `access_token` when talking to the application service, as per [MSC2832](https://github.com/matrix-org/matrix-spec-proposals/pull/2832).

changelogs/client_server/newsfragments/1084.clarification

@@ -1 +0,0 @@
-Mention that the `/rooms/{roomId}/invite` endpoint will return a 200 response if the user is already invited to the room.

changelogs/client_server/newsfragments/1155.clarification

@@ -1 +0,0 @@
-Describe return codes for account data endpoints, and clarify that per-room data does not inherit from the global data.

changelogs/client_server/newsfragments/1161.clarification

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

changelogs/client_server/newsfragments/1164.clarification

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

changelogs/client_server/newsfragments/1165.clarification

@@ -1 +0,0 @@
-Clarify that policy rule globs work like ACL globs. Contributed by Nico.

changelogs/client_server/newsfragments/1166.clarification

@@ -1 +0,0 @@
-Clarify the format of some structures in the End-to-end encryption module.

changelogs/client_server/newsfragments/1170.clarification

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

changelogs/client_server/newsfragments/1174.clarification

@@ -1 +0,0 @@
-Add HTML anchors for object definitions in the formatted specification.

changelogs/client_server/newsfragments/1179.clarification

@@ -1 +0,0 @@
-Tweak the styling of `<code>` snippets in tables rendered from OpenAPI definitions.

changelogs/client_server/newsfragments/1180.clarification

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

changelogs/client_server/newsfragments/1185.clarification

@@ -1 +0,0 @@
-Update "API Standards" section to clarify how JSON is used.

changelogs/client_server/newsfragments/1190.feature

@@ -1 +0,0 @@
-Add a `.m.rule.room.server_acl` push rule to match `m.room.server_acl` events, as per [MSC3786](https://github.com/matrix-org/matrix-spec-proposals/pull/3786).

changelogs/client_server/newsfragments/1196.removal

@@ -1 +0,0 @@
-Remove unused policy room sharing mechanism, as per [MSC3844](https://github.com/matrix-org/matrix-spec-proposals/pull/3844).

changelogs/client_server/newsfragments/1197.feature

@@ -1 +0,0 @@
-Add `Cross-Origin-Resource-Policy` (CORP) headers to media repository, as per [MSC3828](https://github.com/matrix-org/matrix-spec-proposals/pull/3828).

changelogs/client_server/newsfragments/1198.feature

@@ -1 +0,0 @@
-Copy a room's `type` when upgrading it, as per [MSC3818](https://github.com/matrix-org/matrix-spec-proposals/pull/3818).

changelogs/client_server/newsfragments/1199.feature

@@ -1 +0,0 @@
-Add `room_types` filter and `room_type` response to `/publicRooms`, as per [MSC3827](https://github.com/matrix-org/matrix-spec-proposals/pull/3827).

changelogs/client_server/newsfragments/1201.feature

@@ -1 +0,0 @@
-Add a `.m.rule.room.server_acl` push rule to match `m.room.server_acl` events, as per [MSC3786](https://github.com/matrix-org/matrix-spec-proposals/pull/3786).

changelogs/client_server/newsfragments/1210.clarification

@@ -1 +0,0 @@
-Clarify that the "device_id", "user_id" and "access_token" fields are required in the response body of `POST /_matrix/client/v3/login`.

changelogs/client_server/newsfragments/1211.feature

@@ -1 +0,0 @@
-Add `m.replace` relations (event edits), as per [MSC2676](https://github.com/matrix-org/matrix-spec-proposals/pull/2676).

changelogs/client_server/newsfragments/1215.clarification

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

changelogs/client_server/newsfragments/1216.feature.1

@@ -1 +0,0 @@
-Add `m.read.private` receipts, as per [MSC2285](https://github.com/matrix-org/matrix-spec-proposals/pull/2285).

changelogs/client_server/newsfragments/1216.feature.2

@@ -1 +0,0 @@
-Make `m.fully_read` optional on `/read_markers`, as per [MSC2285](https://github.com/matrix-org/matrix-spec-proposals/pull/2285).

changelogs/client_server/newsfragments/1216.feature.3

@@ -1 +0,0 @@
-Allow `m.fully_read` markers to be set from `/receipts`, as per [MSC2285](https://github.com/matrix-org/matrix-spec-proposals/pull/2285).

changelogs/client_server/newsfragments/1236.clarification

@@ -1 +0,0 @@
-Reinforce the relationship of refreshed access tokens to transaction IDs.

changelogs/client_server/newsfragments/1238.clarification

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

changelogs/client_server/newsfragments/1240.clarification

@@ -1 +0,0 @@
-Clarify enum values by separating possible values with commas.

changelogs/client_server/newsfragments/1243.clarification

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

changelogs/client_server/newsfragments/1254.feature

@@ -1 +0,0 @@
-Add threading via `m.thread` relations, as per [MSC3440](https://github.com/matrix-org/matrix-spec-proposals/pull/3440), [MSC3816](https://github.com/matrix-org/matrix-spec-proposals/pull/3816), [MSC3856](https://github.com/matrix-org/matrix-spec-proposals/pull/3856), and [MSC3715](https://github.com/matrix-org/matrix-spec-proposals/pull/3715).

changelogs/client_server/newsfragments/1255.feature

@@ -1 +0,0 @@
-Add per-thread notifications and read receipts, as per [MSC3771](https://github.com/matrix-org/matrix-spec-proposals/pull/3771) and [MSC3773](https://github.com/matrix-org/matrix-spec-proposals/pull/3773).

changelogs/client_server/newsfragments/1261.clarification

@@ -1 +0,0 @@
-Add `thread_id` to the `/receipt` endpoint, as per [MSC3771](https://github.com/matrix-org/matrix-spec-proposals/pull/3771)

changelogs/client_server/newsfragments/1263.clarification

@@ -1 +0,0 @@
-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/2315.feature

@@ -0,0 +1 @@
+Add `M_USER_LIMIT_EXCEEDED` common error code, as per [MSC4335](https://github.com/matrix-org/matrix-spec-proposals/pull/4335).

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/client_server/newsfragments/2328.feature

@@ -0,0 +1 @@
+Add the `is_animated` flag to the `info` object of the `m.image` msgtype and the `m.sticker` event, as per [MSC4230](https://github.com/matrix-org/matrix-spec-proposals/pull/423O).

changelogs/client_server/newsfragments/2329.clarification

@@ -0,0 +1 @@
+Add link to JSON signing algorithm in server-server auth section for clarity. Contributed by @thetayloredman.

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/1174.clarification

@@ -1 +0,0 @@
-Add HTML anchors for object definitions in the formatted specification.

changelogs/identity_service/newsfragments/1185.clarification

@@ -1 +0,0 @@
-Update "API Standards" section to clarify how JSON is used.

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/1191.clarification

@@ -1 +0,0 @@
-Render HTML anchors for object definition tables.

changelogs/internal/newsfragments/1194.feature

@@ -1 +0,0 @@
-Add internal changes changelog section.