.github/CODEOWNERS

@@ -1 +0,0 @@
-*       @matrix-org/spec-core-team

.github/ISSUE_TEMPLATE/config.yaml

@@ -1,4 +1,4 @@
-blank_issues_enabled: false
+blank_issues_enabled: true
 contact_links:
  - name: Matrix Spec Discussion
    url: "https://matrix.to/#/#matrix-spec:matrix.org"

.github/ISSUE_TEMPLATE/release.md

@@ -1,37 +0,0 @@
----
-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/PULL_REQUEST_TEMPLATE/ready-proposal.md

@@ -0,0 +1,19 @@
+---
+name: Proposal ready for review
+about: A proposal that is ready for review by the core team and community.
+title: ''
+labels: proposal, proposal-in-review
+assignees: ''
+
+---
+
+<!-- Put your "rendered" link here -->
+
+### Pull Request Checklist
+
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
+
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] Pull request includes ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
+* [ ] Pull request title and file name include this PR's number as the MSC number.

.github/PULL_REQUEST_TEMPLATE/spec-change.md

@@ -0,0 +1,16 @@
+---
+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
+
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
+
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#other-changes)

.github/PULL_REQUEST_TEMPLATE/wip-proposal.md

@@ -0,0 +1,20 @@
+---
+name: WIP Proposal
+about: A proposal that isn't quite ready for formal review yet.
+title: '[WIP] Your Proposal Title'
+labels: proposal
+assignees: ''
+
+---
+
+<!-- Put your "rendered" link here -->
+
+### Pull Request Checklist
+
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
+
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] A ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
+* [ ] Update the title and file name of your proposal to match this PR's number (after opening).
+* [ ] Ask in [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to get this marked as ready for review, once it is ready for review.

.github/_typos.toml

@@ -1,5 +1,5 @@
 [files]
-extend-exclude = ["/themes", "/attic", "/data-definitions", "*.css", "syntax.scss", "package-lock.json"]
+extend-exclude = ["/themes", "/attic", "/data-definitions", "*.css", "package-lock.json"]
 
 [default]
 check-filename = true
@@ -10,4 +10,3 @@ au1ba7o = "au1ba7o"
 [default.extend-words]
 Appy = "Appy"
 fo = "fo"
-Iy = "Iy"

.github/pull_request_template.md

@@ -1,8 +0,0 @@
-
-### Pull Request Checklist
-
-<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
-
-* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-spec/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
-* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-spec/blob/master/CONTRIBUTING.rst#sign-off)
-* [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-spec/blob/master/CONTRIBUTING.rst#other-changes)

.github/workflows/checks.yaml

@@ -1,18 +0,0 @@
-# workflow steps that ought to pass on a PR, but shouldn't block a preview.
-
-name: "Checks"
-on:
-  pull_request:
- 
-jobs:
-  check-newsfragments:
-    name: "🔎 Check that new newsfragments are valid"
-    if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - run: scripts/check-newsfragments
-        env:
-          PULL_REQUEST_NUMBER: ${{ github.event.number }}

.github/workflows/main.yml

@@ -1,9 +1,4 @@
 name: "Spec"
-
-env:
-  HUGO_VERSION: 0.148.1
-  PYTHON_VERSION: 3.13
-
 on:
   push:
     branches:
@@ -12,10 +7,6 @@ on:
       - v*
   pull_request:
   workflow_dispatch:
-  schedule:
-    # Run this workflow every day at 2am. This helps keep the page of
-    # current spec proposals up-to-date.
-    - cron: '0 2 * * *'
 
 jobs:
   validate-openapi:
@@ -23,71 +14,32 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v2
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v2
         with:
-          node-version: '20'
+          node-version: '14'
-      - name: "🔎 Run validator"
+      - name: "⚙️ npm"
+        working-directory: "./scripts"
         run: |
-          npx @redocly/cli@latest lint data/api/*/*.yaml
+          npm install
+      - 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"
 
-  check-event-examples:
+  check-examples:
     name: "🔎 Check Event schema examples"
     runs-on: ubuntu-latest
+    container: uhoreg/matrix-doc-build
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v2
-      - 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-event-schema-examples.py
+          /env/bin/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"
@@ -104,127 +56,76 @@ jobs:
         # the asterisk matching behaviour, not the literal string.
         run: |
           if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
-              echo "baseURL=/" >> "$GITHUB_OUTPUT"
+              echo ::set-output name=baseURL::/
           elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-              echo "baseURL=/${GITHUB_REF/refs\/tags\//}" >> "$GITHUB_OUTPUT"
+              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
           else
-              echo "baseURL=/unstable" >> "$GITHUB_OUTPUT"
+              echo ::set-output name=baseURL::/unstable
           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@v4
+        uses: actions/checkout@v2
-      - 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: |
-          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+          python3 -m venv env && . env/bin/activate
-            export RELEASE="${GITHUB_REF/refs\/tags\//}"
+          pip install -r scripts/requirements.txt
-          else
-            export RELEASE="unstable"
-          fi
           # The output path matches the final deployment path at spec.matrix.org
-          scripts/dump-openapi.py \
+          scripts/dump-swagger.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-openapi.py \
+          scripts/dump-swagger.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-openapi.py \
+          scripts/dump-swagger.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@v4
+        uses: actions/upload-artifact@v2
         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, generate-changelog]
+    needs: [calculate-baseurl, build-openapi]
-    # run even if generate-changelog was skipped
-    if: ${{ always() }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v2
         with:
-          node-version: '20'
+          node-version: '14'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
+        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
         with:
-          hugo-version: ${{ env.HUGO_VERSION }}
+          hugo-version: '0.85.0'
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v2
+        with:
+          submodules: 'recursive'
       - 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"
+
       # 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@v4
+        uses: actions/download-artifact@v2
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -234,39 +135,11 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v2
         with:
           name: spec-artifact
           path: spec.tar.gz
 
-  htmlcheck:
-    name: "🔎 Validate generated HTML"
-    runs-on: ubuntu-latest
-    needs: [calculate-baseurl, build-spec]
-    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"
-        # 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 }}"
-
-      - 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
@@ -274,29 +147,30 @@ jobs:
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v2
         with:
-          node-version: '20'
+          node-version: '14'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
+        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
         with:
-          hugo-version: ${{ env.HUGO_VERSION }}
+          hugo-version: '0.85.0'
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v2
+        with:
+          submodules: 'recursive'
       - name: "⚙️ npm"
         run: |
           npm i
           npm run get-proposals
       - name: "⚙️ hugo"
-        env:
-          HUGO_PARAMS_VERSION_STATUS: "historical"
         # Create a baseURL like `/v1.2` out of the `v1.2` tag
         run: |
-          hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
+          echo -e '[params.version]\nstatus="historical"' > historical.toml
+          hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
 
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v2
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -306,7 +180,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec-historical.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v2
         with:
           name: spec-historical-artifact
           path: spec-historical.tar.gz

.github/workflows/netlify.yaml

@@ -25,20 +25,17 @@ 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="${OWNER_LOGIN}:${HEAD_BRANCH}"
+          head_branch='${{github.event.workflow_run.head_repository.owner.login}}:${{github.event.workflow_run.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 "prnumber=$pr_number" >> "$GITHUB_OUTPUT"
+          echo "::set-output name=prnumber::$pr_number"
         
       - name: '📥 Download artifact'
-        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
+        uses: dawidd6/action-download-artifact@af92a8455a59214b7b932932f2662fdefbd78126 # v2.15.0
         with:
           workflow: main.yaml
           run_id: ${{ github.event.workflow_run.id }}
@@ -49,7 +46,8 @@ jobs:
         
       - name: "📤 Deploy to Netlify"
         id: netlify
-        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
+        # v1.2.2
+        uses: nwtgck/actions-netlify@f517512ae75beec8896aa7b027c1c72f01816200
         with:
           publish-dir: spec
           deploy-message: "Deploy from GitHub Actions"

.github/workflows/release.yaml

@@ -1,43 +0,0 @@
-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

@@ -1,9 +1,5 @@
 name: Spell Check
-on:
+on: [pull_request]
-  push:
-    branches:
-      - main
-  pull_request:
 
 jobs:
   run:
@@ -11,9 +7,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout Actions Repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v2
 
     - name: Check spelling of proposals
-      uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10
+      uses: crate-ci/typos@master
       with:
         config: ${{github.workspace}}/.github/_typos.toml

.gitignore

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

.gitmodules

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

.htmltest.yml

@@ -1,7 +0,0 @@
-# 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

@@ -1,5 +1,5 @@
-Contributing to matrix-spec
+Contributing to matrix-doc
-===========================
+==========================
 
 Everyone is welcome to contribute to the Matrix specification!
 
@@ -9,10 +9,14 @@ Code style
 ----------
 
 The documentation style is described at
-https://github.com/matrix-org/matrix-spec/blob/main/meta/documentation_style.rst.
+https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst.
 
-Matrix-spec workflows
+Python code within the ``matrix-doc`` project should follow the same style as
----------------------
+synapse, which is documented at
+https://github.com/matrix-org/synapse/tree/master/docs/code_style.md.
+
+Matrix-doc workflows
+--------------------
 
 Specification changes
 ~~~~~~~~~~~~~~~~~~~~~
@@ -23,7 +27,9 @@ server before they can be documented in the specification. This process can take
 some time to complete.
 
 Changes to the protocol (new endpoints, ideas, etc) need to go through the
-`proposals process <https://matrix.org/docs/spec/proposals>`_.
+`proposals process <https://matrix.org/docs/spec/proposals>`_. Other changes,
+such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal.
+If you're not sure, visit us at `#matrix-spec:matrix.org`_ and ask.
 
 Other changes
 ~~~~~~~~~~~~~
@@ -36,12 +42,12 @@ following:
 
 * Addition of features which have been in use in practice for some time, but
   have never made it into the spec (including anything with the `spec-omission
-  <https://github.com/matrix-org/matrix-spec/labels/spec-omission>`_ label).
+  <https://github.com/matrix-org/matrix-doc/labels/spec-omission>`_ label).
 
 * Likewise, corrections to the specification, to fix situations where, in
   practice, servers and clients behave differently to the specification,
   including anything with the `spec-bug
-  <https://github.com/matrix-org/matrix-spec/labels/spec-bug>`_ label.
+  <https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label.
 
   (If there is any doubt about whether it is the spec or the implementations
   that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.)
@@ -49,7 +55,7 @@ following:
 * Clarifications to the specification which do not change the behaviour of
   Matrix servers or clients in a way which might introduce compatibility
   problems for existing deployments. This includes anything with the
-  `clarification <https://github.com/matrix-org/matrix-spec/labels/clarification>`_
+  `clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
   label.
 
   For example, areas where the specification is unclear do not require a proposal
@@ -72,16 +78,12 @@ ask.
 Adding to the changelog
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-All changes to the contents of this repository require a changelog entry. Adding to the changelog can only
+All API specifications 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
+The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the
-form of "news fragments". Depending on which API you changed, an entry should be added to
+form of "news fragments". The news fragments for the client-server API are stored
-each relevant API's ``newsfragments`` directory. A directory exists for each API under
+under ``changelogs/client_server/newsfragments``.
-``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:
@@ -99,16 +101,17 @@ 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
 --------
 
-We ask that everybody who contributes to this project signs off their
+We ask that everybody who contributes to their project signs off their
 contributions, as explained below.
 
 We follow a simple 'inbound=outbound' model for contributions: the act of
@@ -118,10 +121,11 @@ 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>`_,
+same lightweight approach that the Linux Kernel
-`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md>`_, and many other
+(https://www.kernel.org/doc/Documentation/SubmittingPatches), Docker
-projects: the `Developer Certificate of Origin <http://developercertificate.org/>`_
+(https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
-(DCO). This is a simple declaration that you wrote
+projects use: the DCO (Developer Certificate of Origin:
+http://developercertificate.org/). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix::
 
     Developer Certificate of Origin
@@ -165,6 +169,7 @@ include the line in your commit or pull request comment::
 
     Signed-off-by: Your Name <your@email.example.org>
 
-Git allows you to add this signoff automatically when using the ``-s``
+...using your real name; unfortunately pseudonyms and anonymous contributions
-flag to ``git commit``, which uses the name and email set in your
+can't be accepted. Git makes this trivial - just use the -s flag when you do
-``user.name`` and ``user.email`` git configs.
+``git commit``, having first set ``user.name`` and ``user.email`` git configs
+(which you should have done anyway :)

README.md

@@ -1,6 +1,6 @@
 # Matrix Specification
 
-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.
+This repository contains the Matrix Specification, rendered at [spec.matrix.org](http://spec.matrix.org/).
 
 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 OpenAPI definitions and schemas are.
+  parse them. This is also where our Swagger/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,7 +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.
+* `/proposals`: Matrix Spec Change (MSC) proposals. See <https://spec.matrix.org/unstable/proposals/>.
 
 ## Authoring changes to the spec
 
@@ -61,19 +61,20 @@ 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.146.0 is required.
+   v0.74 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 `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
+2. Run `git submodule update --init --recursive` for good measure.
-3. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
+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"
    page and is not required.
-4. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313
+5. 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.
-5. Edit the specification 🙂
+6. 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,16 +87,18 @@ 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 OpenAPI definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
+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-openapi.py` to generate it to `./scripts/openapi/api-docs.json`. To make use of the generated file,
+and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file,
 there are a number of options:
 
-* You can open `./scripts/openapi-preview.html` in your browser, and then open the file by clicking on `Local JSON File`.
+* 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/openapi-http-server.py`, and then view the documentation by
+* You can run a local HTTP server by running `./scripts/swagger-http-server.py`, and then view the documentation via an
-  opening `./scripts/openapi-preview.html` in your browser.
+  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.
 
 ## Issue tracking
 
-Specification issues are tracked on github at <https://github.com/matrix-org/matrix-spec/issues>.
+Specification issues are tracked on github at <https://github.com/matrix-org/matrix-doc/issues>.
 
 See [meta/github-labels.rst](./meta/github-labels.rst) for information on what the labels mean.

assets/css/fonts/Inter.css

@@ -1,63 +0,0 @@
-/* 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/diagrams/membership.drawio

@@ -1 +0,0 @@
-<mxfile host="Electron" modified="2022-02-18T05:31:13.369Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/16.5.1 Chrome/96.0.4664.110 Electron/16.0.7 Safari/537.36" etag="FwSKbslSItXwNPoLLuzM" version="16.5.1" type="device"><diagram id="4a_pTli-mcEMNPq0ciXK" name="Page-1">1VvZkto4FP0aqjIPdNnyBo9peklSnZmeoWayvKQECHC3sSghN5CvHxnLeFMbyeCFh1TQ9ZUX6Zyje6/UPWO02j0SuF5+xTPk9YA22/WMux4Auu4M2H+hZR9ZHE2LDAvizrhTYhi7vxE3xm6BO0ObjCPF2KPuOmucYt9HU5qxQULwNus2x172qWu4QAXDeAq9ovWbO6PLyDoATmL/hNzFMn6ybg+jKysYO/Mv2SzhDG9TJuO+Z4wIxjT6tdqNkBcOXjwuUb+Hd64eX4wgn8p0eNas3x+fbr2x/3O79n9ao2BI+zq/zRv0Av7F7A4v2PX5S9N9PBJoxgaGNzGhS7zAPvTuE+stwYE/Q+HjNNZKfJ4wXjOjzowviNI9n2UYUMxMS7ry+NXiJ/HX2+CATFHZd3BoQLJAtMQPRH7ht6QewAfsEeEVomTPHDh++9qNo5tG1IkgD1L3LQsMyPG1OPblt/tICNynHNZsTOkm9bTn0JA8Cgw5TjhRDDs3nWr+7Ef0Brne8evg+XzDRirbIzUEiekAIxVIFRDl+m8uRQVAZeGyXTKf8RoepnnLxEQSGm+IULSTmUymPZkRAxZvbxNi67E8LVOkjv1Ec50ZPeWhskXs8xBkIAMaJr2Q0g+v7vT1utgIJNloqrFRu9GG9qAKGZvEPwCiSZ3AVhQV7Vz6Pex+Y/HWj9SVux2/86Gxjxs+G4CoE7Di9rFb2Ej6HVpxx/oBYyjLt21Vk+9GEVMAjHABVtLLOfbpA1y5Xjg5Izb+Lgrl5E+0rUdMTbN1MR2IeBf4bTMvxTsWTVhy1NPTvIu71UI948JaLU2zsybbKMy1aJo7xRjLygVsoHXGCFeqSHs0d94Dtsde4XbChsFehL+g5+EtG0+gTfbFq2HHXyTwWLpWuPZhHUw8d9oDoxBDdPpHu4shqLQaOpnVUKuNkqYkJWWTmWYoqRc5ye7zTuzfxGy/N3GnwhixcoNy5W5gti3l4MfqeuSjOx2MlXWVeU9Qll2xQX0rtixgZIPlZuTBLMw0z3O7vGYb+SJL62u2MMhtUWSF+aVWiTL1MQYM69NYx7TPU9kYiPnqlGNlbxF9Je8lKgw2INfaiYBRO0aI+QAwDBi1q4kQs0uAbNKWw3ONSZs8oC+9BsiB17TlwKtcJAe553CSvFskL/gPcrxIFckvVs4R7qm0FdQkUXC1IFihcNgAntULgANg6LUItGXWg3Fdzz3HKN8IsrVS//Y2goBwd6MDsUo1cVdM/zOh6SfkvSHqTuF5LKkrVWQkN0GljRVVcBsxaeIoRysR5CbBanRKtIVhiDRQwdUAVV3OHcs6U84bEL5irvvqY8Embqdz3eN610Su+/W7/up/s/99HgXOuK/dYQT+FpwkCHfDhSN5ZamuZHUox4uKZLRkVw3zFPlMfQA6RD4haIAINOJSU/cTSkUpbwM1p0EzMIYdAk3p11740FLTm/CNnmgSsq+48l3qANNLsFrH/pBMz9Vw53wRl6zvXIaOsgnySToOHKuRSF83c6VzKxPpnyzV5PxbTGOHBUzf7ygiDHe98J0LhUwfH16M/Vuh1QSRYiUzQbauKCJS8bnCmYRcecwQ6AcQ6Idd1/aGIaww85gvKjEXR/xwuQ8nbHhLDyW0GTOCKnpzc5lELi2dPvZRbIre2mmoEq142DPM9WzTaUKqBrnExywvuJlmqX+LJ6+LStV+DaMR6BeDgwYiX/XixdDQzCYADYbZKptuqZWQc/4trr3C8yE8m8tLfdvn5c88a301RTt1IT9zh/yiOPuCbNsb//X58fafh/92v54o+fFZcJw0F3VUDTny19rFZaWkR/H0XHUASu9uqAPQzMhbv8VzcayZ/Mlf5J784aRx/z8=</diagram></mxfile>

assets/diagrams/threaded-dag-threads.drawio

@@ -1 +0,0 @@
-<mxfile host="app.diagrams.net" modified="2022-09-27T03:26:23.216Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" etag="YZcXq9Sm_7Lqw5o2RvSU" version="14.6.7" type="device"><diagram id="_rQ0dgHO1UnHExDn0l7E" name="Page-1">7ZpdU+IwFIZ/DZc6bdNWuJQCujPquOvOrl452TbQaNowIXztr9+EJv0goLCirYwyo81JGpL3PQ8nU2mBIFlcMDiOr2mESMuxokUL9FqO41i+I/7IyDKL2JbvZZERw5GKFYE7/BfpgSo6xRGaVAZySgnH42owpGmKQl6JQcbovDpsSEn1XcdwhIzAXQiJGf2NIx5n0bZzVsQvER7F+p1tv5P1JFAPVjuZxDCi81II9FsgYJTy7CpZBIhI9bQu2X2DLb35whhK+S43/PIf6YMfPSfXNzfx1WP3ez/2ToDaxwySqdrxz5ghGInYudQaJ4jgFKkt8KXWhdFpGiE5td0C3XmMObobw1D2zkUqiFjME6K6hzTlA5hgIrPgEpEZ4jiEsgMTElBC2WpS0O/Jl4jPEJMjyDnBo1T0cTpW09ypJajty4FosVURO9dZZCiiCeJsKYbo9NTWqOT0dHteOO2c+acqY+Oyz201FKr8GuWzFxaIC+XCPo742x3pHrsjAFQdcS3TEdu3Nvhhv5sfruHHNcTpsTuRq7zUHJhO5G59jBO2YcS5If0rYsPJOCsSQ7yQBq2LHAR9byDW2D2Egp2qgsDeoOAGAcG76dc25EKRKHaqSRmP6YimkPSLaLeay8WYKyrTbhV8QpwvVeWGU06rkqMF5vfi2lLXD/JafKRmrd6i1NVb6kYq9nuvJ5CN0l2yWdy2aun7Kiz9FHhOxHZv0Fz8/kETmObGyn2/bKuQiU5ZiF7QUx1tOGQjxF/LWzNNGCKQ41l1HQc33TGg6TYZGsdvGDQueDM0T9NkrMenNEU1cFRC56GM1RaOCPyDSBeGz6PVTkpeDwL5eqlsHRAw8BkAAwZgwZsBOwRIbn5u1afbjlczSs4XSnWh5O6IklMnSuZJu9cElMBaTXLdumuSewwg7Xm2awhI3o4ggTpB8gyQ+o0AyW5eTbINYb5Q+iCU/B1RcutEyXwaN2gCSu76g7K6axLoGEIlpwzBkGOaHgNje577IjiJ8+XLxi3kHLF0FXEstzkYnr2toqmEPLFObfFTSUpbfbjvTKqa/ZZisYliCB0OJ2Jp6ymaL+L/s9b878dFE+g2C6Xv1lwoQXsD3yjC/BjY3rN+fh62Ozuy7dVZYs3KcdkECF3QvNOqZQhz/LQ1BCX9ILrZj1D0KkswfWsETO6HPdcXzeJLFdlBofhuCuj/Aw==</diagram></mxfile>

assets/diagrams/threaded-dag.drawio

@@ -1 +0,0 @@
-<mxfile host="app.diagrams.net" modified="2022-09-27T03:11:43.523Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" etag="L_ujIRop4Jndk67DcTE9" version="14.6.7" type="device"><diagram id="_rQ0dgHO1UnHExDn0l7E" name="Page-1">7VpbU+IwFP41PMqkTS/wKDfdGXXcdWdXn5wsDTTaNkwIAvvrN6UJbYlCF1gbXcYZTU5P0ub0u6S1DdiNFxcMTcJrGuCoYYNg0YC9hm3bwLPFnzSyzCIW8NwsMmYkkLE8cEd+Y5UoozMS4GkpkVMacTIpB4c0SfCQl2KIMTovp41oVD7rBI2xFrgbokiP/iQBD7Noy/bz+CUm41Cd2fLa2ZEYqWS5kmmIAjovhGC/AbuMUp614kUXR2n1VF2ycYM3jq4vjOGEVxnww3ukD17wHF/f3IRXj52v/dA9k7O8oGgmF3wur5YvVQnmIeH4boKGaX8u7nMDdkIeR6JniSaaTrLCj8gCi3N15JSYcbx481qtdQUEdjCNMWdLkaIGQFk0BRtH9uf5PVApYaH8KobkXR+vZ84LIxqyNn9Tp5ZWFhwIoMguZTykY5qgqJ9HO4zOkiAtyapOec4VpRMZfMKcLyXq0YzTcmnxgvB70Qay/ZC2m67s9RaFQ72l6iRivfdqgrRTGJV282Grnho3ogkfoJhEaeA7iQXpbHCD5+L3NxqjZH1j03Vvv62iTHTGhnhLPaUscMTGmO/Cpw4ThiPEyUv5Oo5+022NHB0TyGED08jhn8hxTHLAiuSwayWHr7EjbvKQYRQcjIanWTxR+QlN8IEAadpuASNWNYSApu8WQWLtgEiApuF6AWnnFnGOWbKK2MAR0Qj9wlEHDZ/Hq+V2aUTZqkBw0E1/NoF2iaMXzMkQ1QOvWrUXaujqGqG9vmna2z5p7zHJ4VQkB6xVe52Po71F6QXVALIpvWAHQj6O9FZFV63OroOrZ4L0Qsc06XVP0ntMcrgVyeHUKr3ux5He/ba99ifd9laF13YVOgNNB/pSIitDbjXdOWNoWUiYUJLwaeFst2kgP5WjZpSCp577B2/kW7C1LV80sivYGK0uh45GU1GYTYKsS7A/Z3TK9E0wFMeCTdcwS3FOlnJMznsVOe/Wain6e0ZjLWWv3bz9SXfzVdF16G5+L/dwwYa27XAPG7S25Zfd41jO4GnIHxjhDG3THjXgyReOyVy/InO9Wn1BZ0fcFK4w5IQmRjvDf/+KvSq+Dn2LuJ8ztMrOoH04sOkMbbgt/984g/7fpQsTnME17v2/fZASgJMzlOvZrshcv1ZnAK84Aw4If7ddwrvq/puKXcEQpkIeSDL+vloMyAOi54LXbbCA8wp2UgP2an1abWvQuzRBmD3XNGG2tLKchPkAcqgPQneyo10nOyxdmb+YQA///T6oFN38o9ZsO5h/Gwz7fwA=</diagram></mxfile>

assets/icons/favicon.svg

@@ -1,12 +0,0 @@
-<?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

@@ -1,169 +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.
-*/
-
-/*
-  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("#toc nav 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("#toc nav a.active");
-  for (const activeEntry of activeEntries) {
-    activeEntry.classList.remove('active');
-  }
-
-  // Find the new entry and select it.
-  const newEntry = document.querySelector(`#toc nav 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

@@ -1,114 +0,0 @@
-/*
-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

@@ -1,647 +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 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;
-  }
-
-  .td-sidebar-nav__section .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;
-  }
-
-  a.td-sidebar-link.tree-root {
-    color: $gray-800;
-    font-weight: $font-weight-bold;
-    font-size: 1.3rem;
-    margin-bottom: 0;
-    border-bottom: none;
-  }
-
-  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;
-    }
-  }
-}
-
-@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;
-}
-
-/* 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;
-  }
-
-}
-
-.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

@@ -20,7 +20,7 @@ $dark: #333;
 $gray-100: #FBFBFB;
 
 $secondary-background: #E5F5FB;
-$secondary-lighter-background: #F4FAFC;
+$secondary-lighter-background: #F4FaFC;
 $secondary-lightest-background: #FBFDFD;
 
 
@@ -30,27 +30,12 @@ $note: $secondary;
 $note-background: $secondary-background;
 $warning-background: #FFE0E0;
 
-// colours for definition tables.
+$table-row-alternate: $secondary-lightest-background;
-// the border colour matches that used for "highlight" divs
+$table-row-default: $secondary-lighter-background;
-$table-border-color: rgba(black, .125);
-$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;
 
 /*
- * The $font-family-sans-serif definition here overrides the default value set by docsy
+ Opt to serve fonts locally by overriding web-font-path to be a non-google fonts URL.
- * (https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68)
+ This is only possible with our modified docsy theme: https://github.com/matrix-org/docsy
  */
-$font-family-sans-serif:
+$web-font-path: "../css/fonts/Inter.css";
-  // Add "Inter" to the front, making it the default. The font itself is loaded via stylesheet
+$google_font_name: "Inter";
-  // 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

@@ -0,0 +1,428 @@
+/*
+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";
+
+/* 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-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 heading anchors for site header */
+.td-content {
+  &> h2,
+  &> h3,
+  &> h4,
+  &> h5,
+  &> h6,
+  .rendered-data h1 {
+    scroll-margin-top: 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;
+  }
+}
+
+/* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
+.rendered-data {
+  margin: 1rem 0 3rem 0;
+
+  details {
+
+    summary {
+      padding: .5rem 0;
+      list-style-position: outside;
+    }
+  }
+
+  .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;
+  }
+
+  h2 + table, h3 + table, h3 + div.highlight {
+    margin-top: 0;
+  }
+
+  hr {
+    border-bottom: 2px solid $dark;
+    margin-bottom: 1.5rem;
+  }
+
+  p {
+    max-width: 80%;
+  }
+
+  p code, table code {
+    background-color: $white;
+  }
+
+  table {
+    table-layout: fixed;
+    width: 100%;
+    margin: 4rem 0;
+
+    caption {
+      caption-side: top;
+      color: $dark;
+      font-size: 1rem;
+      font-weight: $font-weight-bold;
+    }
+
+    th, td, caption {
+      padding: 1rem;
+    }
+
+    th {
+      background-color: $white;
+    }
+
+    caption, tr {
+      background-color: $table-row-default;
+    }
+
+    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;
+      background-color: $white;
+    }
+
+    &.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;
+}

assets/scss/syntax.scss

@@ -1,82 +0,0 @@
-/* Background */ .chroma { background-color: #f8f8f8 }
-/* Other */ .chroma .x { color: #000000 }
-/* Error */ .chroma .err { color: #a40000 }
-/* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
-/* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; width: auto; overflow: auto; display: block; }
-/* LineHighlight */ .chroma .hl { display: block; width: 100%;background-color: #ffffcc }
-/* LineNumbersTable */ .chroma .lnt { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
-/* LineNumbers */ .chroma .ln { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
-/* Keyword */ .chroma .k { color: #204a87; font-weight: bold }
-/* KeywordConstant */ .chroma .kc { color: #204a87; font-weight: bold }
-/* KeywordDeclaration */ .chroma .kd { color: #204a87; font-weight: bold }
-/* KeywordNamespace */ .chroma .kn { color: #204a87; font-weight: bold }
-/* KeywordPseudo */ .chroma .kp { color: #204a87; font-weight: bold }
-/* KeywordReserved */ .chroma .kr { color: #204a87; font-weight: bold }
-/* KeywordType */ .chroma .kt { color: #204a87; font-weight: bold }
-/* Name */ .chroma .n { color: #000000 }
-/* NameAttribute */ .chroma .na { color: #c4a000 }
-/* NameBuiltin */ .chroma .nb { color: #204a87 }
-/* NameBuiltinPseudo */ .chroma .bp { color: #3465a4 }
-/* NameClass */ .chroma .nc { color: #000000 }
-/* NameConstant */ .chroma .no { color: #000000 }
-/* NameDecorator */ .chroma .nd { color: #5c35cc; font-weight: bold }
-/* NameEntity */ .chroma .ni { color: #ce5c00 }
-/* NameException */ .chroma .ne { color: #cc0000; font-weight: bold }
-/* NameFunction */ .chroma .nf { color: #000000 }
-/* NameFunctionMagic */ .chroma .fm { color: #000000 }
-/* NameLabel */ .chroma .nl { color: #f57900 }
-/* NameNamespace */ .chroma .nn { color: #000000 }
-/* NameOther */ .chroma .nx { color: #000000 }
-/* NameProperty */ .chroma .py { color: #000000 }
-/* NameTag */ .chroma .nt { color: #204a87; font-weight: bold }
-/* NameVariable */ .chroma .nv { color: #000000 }
-/* NameVariableClass */ .chroma .vc { color: #000000 }
-/* NameVariableGlobal */ .chroma .vg { color: #000000 }
-/* NameVariableInstance */ .chroma .vi { color: #000000 }
-/* NameVariableMagic */ .chroma .vm { color: #000000 }
-/* Literal */ .chroma .l { color: #000000 }
-/* LiteralDate */ .chroma .ld { color: #000000 }
-/* LiteralString */ .chroma .s { color: #4e9a06 }
-/* LiteralStringAffix */ .chroma .sa { color: #4e9a06 }
-/* LiteralStringBacktick */ .chroma .sb { color: #4e9a06 }
-/* LiteralStringChar */ .chroma .sc { color: #4e9a06 }
-/* LiteralStringDelimiter */ .chroma .dl { color: #4e9a06 }
-/* LiteralStringDoc */ .chroma .sd { color: #8f5902; font-style: italic }
-/* LiteralStringDouble */ .chroma .s2 { color: #4e9a06 }
-/* LiteralStringEscape */ .chroma .se { color: #4e9a06 }
-/* LiteralStringHeredoc */ .chroma .sh { color: #4e9a06 }
-/* LiteralStringInterpol */ .chroma .si { color: #4e9a06 }
-/* LiteralStringOther */ .chroma .sx { color: #4e9a06 }
-/* LiteralStringRegex */ .chroma .sr { color: #4e9a06 }
-/* LiteralStringSingle */ .chroma .s1 { color: #4e9a06 }
-/* LiteralStringSymbol */ .chroma .ss { color: #4e9a06 }
-/* LiteralNumber */ .chroma .m { color: #0000cf; font-weight: bold }
-/* LiteralNumberBin */ .chroma .mb { color: #0000cf; font-weight: bold }
-/* LiteralNumberFloat */ .chroma .mf { color: #0000cf; font-weight: bold }
-/* LiteralNumberHex */ .chroma .mh { color: #0000cf; font-weight: bold }
-/* LiteralNumberInteger */ .chroma .mi { color: #0000cf; font-weight: bold }
-/* LiteralNumberIntegerLong */ .chroma .il { color: #0000cf; font-weight: bold }
-/* LiteralNumberOct */ .chroma .mo { color: #0000cf; font-weight: bold }
-/* Operator */ .chroma .o { color: #ce5c00; font-weight: bold }
-/* OperatorWord */ .chroma .ow { color: #204a87; font-weight: bold }
-/* Punctuation */ .chroma .p { color: #000000; font-weight: bold }
-/* Comment */ .chroma .c { color: #8f5902; font-style: italic }
-/* CommentHashbang */ .chroma .ch { color: #8f5902; font-style: italic }
-/* CommentMultiline */ .chroma .cm { color: #8f5902; font-style: italic }
-/* CommentSingle */ .chroma .c1 { color: #8f5902; font-style: italic }
-/* CommentSpecial */ .chroma .cs { color: #8f5902; font-style: italic }
-/* CommentPreproc */ .chroma .cp { color: #8f5902; font-style: italic }
-/* CommentPreprocFile */ .chroma .cpf { color: #8f5902; font-style: italic }
-/* Generic */ .chroma .g { color: #000000 }
-/* GenericDeleted */ .chroma .gd { color: #a40000 }
-/* GenericEmph */ .chroma .ge { color: #000000; font-style: italic }
-/* GenericError */ .chroma .gr { color: #ef2929 }
-/* GenericHeading */ .chroma .gh { color: #000080; font-weight: bold }
-/* GenericInserted */ .chroma .gi { color: #00a000 }
-/* GenericOutput */ .chroma .go { color: #000000; font-style: italic }
-/* GenericPrompt */ .chroma .gp { color: #8f5902 }
-/* GenericStrong */ .chroma .gs { color: #000000; font-weight: bold }
-/* GenericSubheading */ .chroma .gu { color: #800080; font-weight: bold }
-/* GenericTraceback */ .chroma .gt { color: #a40000; font-weight: bold }
-/* GenericUnderline */ .chroma .gl { color: #000000; text-decoration: underline }
-/* TextWhitespace */ .chroma .w { color: #f8f8f8; text-decoration: underline }

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
+A description of how email addresses, mobile phone numbers and other third
-identifiers can be used to authenticate and discover users in Matrix.
+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/3171.feature

@@ -0,0 +1 @@
+Describe "Common Namespaced Identifier Grammar" as per [MSC2758](https://github.com/matrix-org/matrix-doc/pull/2758).

changelogs/appendices/newsfragments/3608.feature

@@ -0,0 +1 @@
+Describe the `matrix:` URI scheme as per [MSC2312](https://github.com/matrix-org/matrix-doc/pull/2312).

changelogs/application_service/newsfragments/3658.clarification

@@ -0,0 +1 @@
+Distinguish between "federation" event format as exchanged by the Federation API, and the "client" event formats as used in the client-server and AS APIs.

changelogs/application_service/newsfragments/3674.clarification

@@ -0,0 +1 @@
+Fix the rendering of the responses for various API endpoints.

changelogs/application_service/newsfragments/3675.clarification

@@ -0,0 +1 @@
+Correct the documentation for the response value for `GET /_matrix/app/v1/thirdparty/protocol/{protocol}`.

changelogs/client_server/newsfragments/3324.feature

@@ -0,0 +1 @@
+Extend `/_matrix/client/r0/login` to accept a `m.login.appservice`, as per [MSC2778](https://github.com/matrix-org/matrix-doc/pull/2778).

changelogs/client_server/newsfragments/3387.feature

@@ -0,0 +1 @@
+Add support for `restricted` rooms as per [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083), [MSC3289](https://github.com/matrix-org/matrix-doc/pull/3289), and [MSC3375](https://github.com/matrix-org/matrix-doc/pull/3375).

changelogs/client_server/newsfragments/3481.clarification

@@ -0,0 +1 @@
+Make `AesHmacSha2KeyDescription` consistent with `KeyDescription` in marking `name` as optional.

changelogs/client_server/newsfragments/3482.clarification

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

changelogs/client_server/newsfragments/3492.clarification

@@ -0,0 +1 @@
+Explicitly mention RFC5870 in the definition of `m.location` events

changelogs/client_server/newsfragments/3495.clarification

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

changelogs/client_server/newsfragments/3509.clarification

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

changelogs/client_server/newsfragments/3524.breaking

@@ -0,0 +1 @@
+The `prev_content` field is now returned inside the `unsigned` property of events, rather than at the top level, as per [MSC3442](https://github.com/matrix-org/matrix-doc/pull/3442).

changelogs/client_server/newsfragments/3530.clarification

@@ -0,0 +1 @@
+Add `403 M_FORBIDDEN` error code to `/profile/{userId}` as per [MSC3550](https://github.com/matrix-org/matrix-doc/pull/3550).

changelogs/client_server/newsfragments/3535.clarification

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

changelogs/client_server/newsfragments/3543.clarification

@@ -0,0 +1 @@
+Clarify the description of the `/sync` API, including a fix to an ASCII art diagram.

changelogs/client_server/newsfragments/3562.clarification

@@ -0,0 +1 @@
+Clarify that `base_url` in client `well_known` may or may not include trailing slash.

changelogs/client_server/newsfragments/3573.clarification

@@ -0,0 +1 @@
+Clarify which signature to check when decrypting `m.olm.v1.curve25519-aes-sha2` messages.

changelogs/client_server/newsfragments/3591.clarification

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

changelogs/client_server/newsfragments/3601.clarification

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

changelogs/client_server/newsfragments/3605.feature.1

@@ -0,0 +1 @@
+Add `is_guest` to `/account/whoami` as per [MSC3069](https://github.com/matrix-org/matrix-doc/pull/3069).

changelogs/client_server/newsfragments/3605.feature.2

@@ -0,0 +1 @@
+Expand guest access to sending any room event and state event as per [MSC3419](https://github.com/matrix-org/matrix-doc/pull/3419).

changelogs/client_server/newsfragments/3606.clarification

@@ -0,0 +1 @@
+Clarify what "Stripped State" is and what purpose it serves, as per [MSC3173](https://github.com/matrix-org/matrix-doc/pull/3173).

changelogs/client_server/newsfragments/3610.feature

@@ -0,0 +1 @@
+Add Spaces and room types as per [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) and [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946).

changelogs/client_server/newsfragments/3610.new

@@ -0,0 +1 @@
+Add the Space Hierarchy API (`GET /_matrix/client/v1/rooms/{roomId}/hierarchy`) as per [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946).

changelogs/client_server/newsfragments/3611.clarification

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

changelogs/client_server/newsfragments/3614.feature

@@ -0,0 +1 @@
+Add new `m.set_displayname`, `m.set_avatar_url`, and `m.3pid_changes` capabilities as per [MSC3283](https://github.com/matrix-org/matrix-doc/pull/3283).

changelogs/client_server/newsfragments/3615.feature

@@ -0,0 +1 @@
+Add support for fallback keys (optional keys used once one-time keys run out), as per [MSC2732](https://github.com/matrix-org/matrix-doc/pull/2732).

changelogs/client_server/newsfragments/3616.feature

@@ -0,0 +1 @@
+Add token-authenticated registration support as per [MSC3231](https://github.com/matrix-org/matrix-doc/pull/3231).

changelogs/client_server/newsfragments/3616.new

@@ -0,0 +1 @@
+Add `/_matrix/client/v1/register/m.login.registration_token/validity` as per [MSC3231](https://github.com/matrix-org/matrix-doc/pull/3231).

changelogs/client_server/newsfragments/3624.breaking

@@ -0,0 +1 @@
+The `aliases` property from the chunks returned by `/publicRooms`, as per [MSC2432](https://github.com/matrix-org/matrix-doc/pull/2432).

changelogs/client_server/newsfragments/3636.clarification

@@ -0,0 +1 @@
+Clarify how to interpret missing one-time key counts.

changelogs/client_server/newsfragments/3650.clarification

@@ -0,0 +1 @@
+Correct the schema for the responses  for various API endpoints.

changelogs/client_server/newsfragments/3652.clarification

@@ -0,0 +1 @@
+Clarify that group mentions are no longer in the specification.

changelogs/client_server/newsfragments/3658.clarification

@@ -0,0 +1 @@
+Distinguish between "federation" event format as exchanged by the Federation API, and the "client" event formats as used in the client-server and AS APIs.

changelogs/client_server/newsfragments/3671.clarification

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

changelogs/client_server/newsfragments/3674.clarification

@@ -0,0 +1 @@
+Fix the rendering of the responses for various API endpoints.

changelogs/client_server/newsfragments/3680.clarification

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

changelogs/header.md

@@ -0,0 +1,16 @@
+<!--
+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-doc/tree/VERSION">https://github.com/matrix-org/matrix-doc/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/3610.feature

@@ -0,0 +1 @@
+Add the `room_type` to stored invites as per [MSC3288](https://github.com/matrix-org/matrix-doc/pull/3288).

changelogs/identity_service/newsfragments/3674.clarification

@@ -0,0 +1 @@
+Fix the rendering of the responses for various API endpoints.

changelogs/internal/newsfragments/2282.clarification

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

changelogs/legacy/application_service.rst

@@ -22,5 +22,5 @@ r0.1.0
 
 This is the first release of the Application Service specification. It
 includes support for application services being able to interact with
-homeservers and bridge third-party networks, such as IRC, over to Matrix
+homeservers and bridge third party networks, such as IRC, over to Matrix
 in a standard and accessible way.

changelogs/legacy/client_server.rst

@@ -211,7 +211,7 @@ Backwards Compatible Changes
 - Add a common standard for user, room, and group mentions in messages. (`#1547 <https://github.com/matrix-org/matrix-doc/issues/1547>`_)
 - Add server ACLs as an option for controlling federation in a room. (`#1550 <https://github.com/matrix-org/matrix-doc/issues/1550>`_)
 - Add new push rules for encrypted events and ``@room`` notifications. (`#1551 <https://github.com/matrix-org/matrix-doc/issues/1551>`_)
-- Add third-party network room directories, as provided by application services. (`#1554 <https://github.com/matrix-org/matrix-doc/issues/1554>`_)
+- Add third party network room directories, as provided by application services. (`#1554 <https://github.com/matrix-org/matrix-doc/issues/1554>`_)
 - Document the ``validated_at`` and ``added_at`` fields on ``GET /acount/3pid``. (`#1567 <https://github.com/matrix-org/matrix-doc/issues/1567>`_)
 - Add an ``inhibit_login`` registration option. (`#1589 <https://github.com/matrix-org/matrix-doc/issues/1589>`_)
 - Recommend that servers set a Content Security Policy for the content repository. (`#1600 <https://github.com/matrix-org/matrix-doc/issues/1600>`_)
@@ -554,7 +554,7 @@ Since the draft stage, the following major changes have been made:
   - Push notification
   - History visibility
   - Search
-  - Invites based on third-party identifiers
+  - Invites based on third party identifiers
   - Room tagging
   - Guest access
   - Client config

changelogs/legacy/identity_service.rst

@@ -48,7 +48,7 @@ r0.1.0
 ======
 
 This is the first release of the Identity Service API. With this API, clients and
-homeservers can store bindings between third-party identifiers such as email addresses
+homeservers can store bindings between third party identifiers such as email addresses
 and phone numbers, associating them with Matrix user IDs. Additionally, identity
-servers offer the ability to invite third-party users to Matrix rooms by storing
+servers offer the ability to invite third party users to Matrix rooms by storing
 the invite until the identifier is bound.

changelogs/push_gateway/newsfragments/3674.clarification

@@ -0,0 +1 @@
+Fix the rendering of the responses for various API endpoints.

changelogs/pyproject.toml

@@ -1,66 +1,39 @@
 [tool.towncrier]
     version = "unused"
-    filename = "rendered.md"
+    filename = "../rendered.md"
-    template = "template.md.jinja"
+    issue_format = "[#{issue}](https://github.com/matrix-org/matrix-doc/issues/{issue})"
+    title_format = "### {name}"  # Matches rendered spec, even if awkward
+    underlines = "   "  # 3 spaces intentionally to hide RST headings
+
+    # Note: The names below have the <strong> tag built-in so the rendered spec *and* the generated
+    # changelog can benefit from sane headings.
 
     [[tool.towncrier.type]]
         directory = "breaking"
-        name = "Breaking Changes"
+        name = "<strong>Breaking Changes</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "deprecation"
-        name = "Deprecations"
+        name = "<strong>Deprecations</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "new"
-        name = "New Endpoints"
+        name = "<strong>New Endpoints</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "removal"
-        name = "Removed Endpoints"
+        name = "<strong>Removed Endpoints</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "feature"
-        name = "Backwards Compatible Changes"
+        name = "<strong>Backwards Compatible Changes</strong>"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "clarification"
-        name = "Spec Clarifications"
+        name = "<strong>Spec Clarifications</strong>"
         showcontent = true
-
-    [[tool.towncrier.section]]
-        name = "Client-Server API"
-        path = "client_server"
-
-    [[tool.towncrier.section]]
-        name = "Server-Server API"
-        path = "server_server"
-    
-    [[tool.towncrier.section]]
-        name = "Application Service API"
-        path = "application_service"
-
-    [[tool.towncrier.section]]
-        name = "Identity Service API"
-        path = "identity_service"
-    
-    [[tool.towncrier.section]]
-        name = "Push Gateway API"
-        path = "push_gateway"
-    
-    [[tool.towncrier.section]]
-        name = "Room Versions"
-        path = "room_versions"
-    
-    [[tool.towncrier.section]]
-        name = "Appendices"
-        path = "appendices"
-
-    [[tool.towncrier.section]]
-        name = "Internal Changes/Tooling"
-        path = "internal"

changelogs/room_versions/newsfragments/3387.feature.1

@@ -0,0 +1 @@
+Add Room Version 8 as per [MSC3289](https://github.com/matrix-org/matrix-doc/pull/3289).

changelogs/room_versions/newsfragments/3387.feature.2

@@ -0,0 +1 @@
+Add Room Version 9 as per [MSC3375](https://github.com/matrix-org/matrix-doc/pull/3375).

changelogs/room_versions/newsfragments/3432.clarification

@@ -0,0 +1 @@
+Fully specify room versions to indicate what exactly is carried over from parent versions.

changelogs/room_versions/newsfragments/3501.clarification

@@ -0,0 +1 @@
+Clarifications to sections on event IDs and event formats.

changelogs/room_versions/newsfragments/3522.clarification

@@ -0,0 +1 @@
+Remove a number of fields which were incorrectly shown to form part of the `unsigned` data of a Federation PDU.

changelogs/room_versions/newsfragments/3661.clarification

@@ -0,0 +1 @@
+Fully specify room versions to indicate what exactly is carried over from parent versions.

changelogs/room_versions/newsfragments/3683.clarification.1

@@ -0,0 +1 @@
+Fix heading order of room version specifications to be consistent.

changelogs/room_versions/newsfragments/3683.clarification.2

@@ -0,0 +1 @@
+Add missing "Signing key validity period" section to room version 6.

changelogs/room_versions/newsfragments/3694.clarification

@@ -0,0 +1 @@
+Fix auth rules to allow membership of `knock` -> `leave` in v7, v8, and v9.

changelogs/server_server/3528.clarification

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

changelogs/server_server/newsfragments/3387.feature

@@ -0,0 +1 @@
+Add support for `restricted` rooms as per [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083), [MSC3289](https://github.com/matrix-org/matrix-doc/pull/3289), and [MSC3375](https://github.com/matrix-org/matrix-doc/pull/3375).

changelogs/server_server/newsfragments/3527.clarification

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

changelogs/server_server/newsfragments/3583.clarification

@@ -0,0 +1 @@
+Clarify that `GET /_matrix/federation/v1/event_auth/{roomId}/{eventId}` does *not* return the auth chain for the full state of the room.

changelogs/server_server/newsfragments/3610.new

@@ -0,0 +1 @@
+Add the Space Hierarchy API (`GET /_matrix/federation/v1/hierarchy/{roomId}`) as per [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946).

changelogs/server_server/newsfragments/3660.new

@@ -0,0 +1 @@
+Add the Space Hierarchy API (`GET /_matrix/federation/v1/hierarchy/{roomId}`) as per [MSC2946](https://github.com/matrix-org/matrix-doc/pull/2946).

changelogs/server_server/newsfragments/3674.clarification

@@ -0,0 +1 @@
+Fix the rendering of the responses for various API endpoints.

changelogs/template.md.jinja

@@ -1,24 +0,0 @@
-{% for section_name, section in sections.items() %}
-{% if section_name %}
-
-## {{section_name}}
-{% endif %}
-
-{% if section %}
-{% for category, val in definitions.items() if category in section %}
-**{{ definitions[category]['name'] }}**
-
-{% for content, issues in section[category].items() %}
-- {{ content }} (
-{%- for issue in issues %}
-[{{issue}}](https://github.com/matrix-org/matrix-spec/issues/{{issue|trim('#')}}){% if not loop.last %}, {% endif %}
-{%- endfor %}
-)
-{% endfor %}
-
-{% endfor %}
-{% else %}
-No significant changes.
-
-{% endif %}
-{% endfor %}

config.toml

@@ -0,0 +1,84 @@
+baseURL = "/"
+title = "Matrix Specification"
+
+# Prepends absolute URLs with the baseURL. Useful when hosting on non-root
+# paths, such as /unstable.
+canonifyURLs = true
+
+enableRobotsTXT = true
+
+# Hugo allows theme composition (and inheritance). The precedence is from left to right.
+theme = ["docsy"]
+
+disableKinds = ["taxonomy", "taxonomyTerm"]
+
+[languages]
+[languages.en]
+title = "Matrix Specification"
+description = "Home of the Matrix specification for decentralised communication"
+languageName ="English"
+# Weight used for sorting.
+weight = 1
+
+[markup]
+  [markup.goldmark]
+    [markup.goldmark.renderer]
+      # Enables us to render raw HTML
+      unsafe = true
+  [markup.highlight]
+      # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
+      style = "tango"
+
+# Everything below this are Site Params
+
+[params]
+copyright = "The Matrix.org Foundation CIC"
+privacy_policy = "https://matrix.org/legal/privacy-notice"
+
+[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"
+# 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 = "2"
+release_date = "February 02, 2022"
+
+# 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
+
+[params.links]
+# End user relevant links. These will show up on left side of footer and in the community page if you have one.
+# [[params.links.user]]
+# 	name = "User mailing list"
+# 	url = "https://example.org/mail"
+# 	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]]
+	name = "GitHub"
+	url = "https://github.com/matrix-org"
+	icon = "fab fa-github"
+  desc = "Matrix on GitHub"
+[[params.links.developer]]
+	name = "GitLab"
+	url = "https://gitlab.matrix.org/matrix-org"
+	icon = "fab fa-gitlab"
+  desc = "Matrix on GitLab"
+[[params.links.developer]]
+	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"