Merge d89d879e23 into 70c7d59caa

To match the rest of the theme.

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

.github/workflows/main.yml

@@ -196,6 +196,8 @@ jobs:
     needs: [calculate-baseurl, build-openapi, generate-changelog]
     # run even if generate-changelog was skipped
     if: ${{ always() }}
+    env:
+      baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
     steps:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
@@ -218,8 +220,10 @@ jobs:
         with:
           name: changelog-artifact
           path: content/changelog
+
       - name: "⚙️ hugo"
-        run: hugo --baseURL "${{ needs.calculate-baseurl.outputs.baseURL }}" -d "spec"
+        run: hugo --baseURL "${baseURL}" -d "spec${baseURL}"
+
       # We manually unpack the spec OpenAPI definition JSON to the website tree
       # to make it available to the world in a canonical place:
       # https://spec.matrix.org/latest/client-server-api/api.json
@@ -230,10 +234,13 @@ jobs:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
         run: |
-          tar -xzf openapi.tar.gz
+          tar -C "spec${baseURL}" --strip-components=1 -xzf openapi.tar.gz
 
       - name: "📦 Tarball creation"
-        run: tar -czf spec.tar.gz spec
+        run: |
+          cd spec
+          tar -czf ../spec.tar.gz *
+
       - name: "📤 Artifact upload"
         uses: actions/upload-artifact@v4
         with:
@@ -244,6 +251,14 @@ jobs:
     name: "🔎 Validate generated HTML"
     runs-on: ubuntu-latest
     needs: [calculate-baseurl, build-spec]
+    # Run even if `generate-changelog` was skipped.
+    #
+    # `build-spec` has a dependency on `generate-changelog` to ensure order of execution
+    # and to access `needs.generate-changelog.result`. However, `generate-changelog` is
+    # skipped on tag builds; even a transient dependency on `generate-changelog` is then
+    # enough for this step to also be skipped by default on tag builds. Hence the need for
+    # this explicit `if`.
+    if: ${{ !failure() && !cancelled() }}
     steps:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
@@ -254,14 +269,9 @@ jobs:
           name: spec-artifact
 
       - name: "📝 Unpack the spec"
-        # we have to unpack it into the right path given the baseurl, so that the
-        # links are correct.
-        # eg if baseurl is `/unstable`, we want to put the site in `spec/unstable`.
         run: |
-          mkdir -p "spec${baseURL}"
-          tar -C "spec${baseURL}" --strip-components=1 -xvzf spec.tar.gz
-        env:
-          baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
+          mkdir spec
+          tar -C spec -xvzf spec.tar.gz
 
       - name: "Run htmltest"
         uses: wjdp/htmltest-action@master
@@ -271,8 +281,10 @@ jobs:
   build-historical-spec:
     name: "📖 Build the historical backup spec"
     runs-on: ubuntu-latest
-    needs: [build-openapi]
+    needs: [calculate-baseurl, build-openapi]
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
+    env:
+      baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
     steps:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
@@ -292,9 +304,8 @@ jobs:
       - 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"
+          hugo --baseURL "${baseURL}" -d "spec${baseURL}"
 
       - name: "📥 Spec definition download"
         uses: actions/download-artifact@v4
@@ -302,12 +313,51 @@ jobs:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
         run: |
-          tar -xzf openapi.tar.gz
+          tar -C "spec${baseURL}" --strip-components=1 -xzf openapi.tar.gz
 
       - name: "📦 Tarball creation"
-        run: tar -czf spec-historical.tar.gz spec
+        run: |
+          cd spec
+          tar -czf ../spec-historical.tar.gz *
+
       - name: "📤 Artifact upload"
         uses: actions/upload-artifact@v4
         with:
           name: spec-historical-artifact
           path: spec-historical.tar.gz
+
+  # If we're building a tag, create a release and publish the artifacts
+  create_release:
+    name: "Create release"
+    if: ${{ !failure() && !cancelled() && startsWith(github.ref, 'refs/tags/') }}
+    needs:
+      - build-spec
+      - build-historical-spec
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Check out changelogs"
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+        with:
+          sparse-checkout: |
+            content/changelog
+      - name: "📥 Download built spec"
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: spec-artifact
+      - name: "📥 Download historical spec artifact"
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: spec-historical-artifact
+      - name: "✨ Create draft release"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Remove front-matter from changelog
+          sed '1,/^---$/d' "content/changelog/${{ github.ref_name }}.md" > changelog.md
+
+          # Create a draft release, using the changelog as release notes, and attaching the spec artifacts.
+          gh release create -d -t "${{ github.ref_name }}" \
+            -F "changelog.md" \
+            "${{ github.ref_name }}" \
+            spec.tar.gz \
+            spec-historical.tar.gz

.github/workflows/netlify.yaml

@@ -45,7 +45,9 @@ jobs:
           name: spec-artifact
 
       - name: "📦 Extract Artifacts"
-        run: tar -xzvf spec.tar.gz && rm spec.tar.gz
+        run: |
+          mkdir spec
+          tar -C spec -xzvf spec.tar.gz && rm spec.tar.gz
         
       - name: "📤 Deploy to Netlify"
         id: netlify

assets/js/toc.js

@@ -50,7 +50,7 @@ function getHeadings() {
   let headings = [];
 
   // First get the anchors in the ToC.
-  const toc_anchors = document.querySelectorAll("#toc nav a");
+  const toc_anchors = document.querySelectorAll("#TableOfContents a");
 
   for (const anchor of toc_anchors) {
     // Then get the heading from its selector in the anchor's href.
@@ -59,7 +59,7 @@ function getHeadings() {
       console.error("Got ToC anchor without href");
       continue;
     }
-    
+
     const heading = document.querySelector(selector);
     if (!heading) {
       console.error("Heading not found for selector:", selector);
@@ -122,13 +122,13 @@ function getCurrentHeading(headings, headerOffset) {
 */
 function selectTocEntry(id) {
   // Deselect previously selected entries.
-  const activeEntries = document.querySelectorAll("#toc nav a.active");
+  const activeEntries = document.querySelectorAll("#TableOfContents a.active");
   for (const activeEntry of activeEntries) {
     activeEntry.classList.remove('active');
   }
 
   // Find the new entry and select it.
-  const newEntry = document.querySelector(`#toc nav a[href="#${id}"]`);
+  const newEntry = document.querySelector(`#TableOfContents a[href="#${id}"]`);
   if (!newEntry) {
     console.error("ToC entry not found for ID:", id);
     return;

assets/scss/_styles_project.scss

@@ -76,52 +76,126 @@ Custom SCSS for the Matrix spec
   scroll-behavior: smooth;
   overscroll-behavior: contain;
 
-  &>.td-sidebar-nav__section {
+  & > .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;
+    .ul-1 ul {
+      padding-left: 0;
     }
 
-    &.active, &active:hover {
-      background-color: $secondary-background;
+    /* This is to make the width of the items that have sub-items (like room versions)
+    the same as the width of items that don't (like changelog) */
+    .pr-md-3, .px-md-3 {
+      padding-right: 0 !important;
+    }
+
+    .ul-1 > li > a {
+      padding-left: 1rem !important;
+    }
+
+    .ul-2 > li > a {
+      padding-left: 2rem !important;
+    }
+  }
+
+  /* Styles for the table of contents */
+  & > .td-toc {
+    padding-top: 1rem;
+    padding-left: 1.5rem;
+    /* Add border above the toc */
+    border-top: 1px solid var(--bs-tertiary-color);
+
+    ol {
+      padding-left: 1rem;
+      counter-reset: section;
+      list-style-type: none;
+    }
+
+    #TableOfContents {
+      /* Remove the space between the title and the ToC */
+      margin-top: 0;
+
+      &>ol>li {
+        margin-bottom: .5rem;
+
+        &>a {
+          font-weight: $font-weight-bold;
+        }
+      }
+
+      ol {
+        padding-left: 0;
+      }
+
+      &>ol>li>a {
+        padding-left: 1rem;
+      }
+
+      &>ol>li>ol>li>a {
+        padding-left: 2rem;
+      }
+
+      &>ol>li>ol>li>ol>li>a {
+        padding-left: 3rem;
+      }
+
+      &>ol>li>ol>li>ol>li>ol>li>a {
+        padding-left: 4rem;
+      }
+
+      &>ol>li>ol>li>ol>li>ol>li>ol>li>a {
+        padding-left: 5rem;
+      }
+
+    }
+
+    li a:before {
+      counter-increment: section;
+      content: counters(section, ".") " ";
+    }
+
+    .td-toc-title {
+      font-weight: $font-weight-bold;
+      font-size: 1.3rem;
+
+      /* Remove the border under the title */
+      border-bottom: 0;
+      /* Remove the space under the title */
+      margin-bottom: 0;
+
+      /* Fix the top of page link color */
+      a, a:hover {
+        color: $secondary;
+      }
+    }
+  }
+
+  /* Apply the same style to links in the navigation and in the ToC */
+  & > .td-sidebar-nav__section, & > .td-toc #TableOfContents {
+    li a.td-sidebar-link.tree-root {
+      color: $gray-800;
+      font-weight: $font-weight-bold;
+      font-size: 1.3rem;
+      margin-bottom: 0;
+      border-bottom: none;
+    }
+
+    li a, li a.td-sidebar-link {
+      color: $gray-800;
+      font-weight: $font-weight-normal;
+      padding-top: .2rem;
+      padding-bottom: .2rem;
+
+      transition: all 100ms ease-in-out;
+
+      &:hover {
+        background-color: $secondary-lighter-background;
+        color: $gray-800;
+      }
+
+      &.active, &active:hover {
+        background-color: $secondary-background;
+      }
     }
   }
 }
@@ -199,64 +273,6 @@ Custom SCSS for the Matrix spec
   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;

assets/scss/_variables_project.scss

@@ -18,6 +18,7 @@ $primary: #FFF;
 $secondary: #0098D4;
 $dark: #333;
 $gray-100: #FBFBFB;
+$code-color: #005b7f;
 
 $secondary-background: #E5F5FB;
 $secondary-lighter-background: #F4FAFC;

changelogs/client_server/newsfragments/2280.clarification

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

changelogs/client_server/newsfragments/2283.clarification

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

changelogs/internal/newsfragments/2222.clarification

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

changelogs/internal/newsfragments/2275.clarification

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

changelogs/internal/newsfragments/2276.feature

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

changelogs/internal/newsfragments/2289.clarification

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

changelogs/server_server/newsfragments/2288.clarification

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

config/_default/hugo.toml

@@ -166,3 +166,10 @@ sidebar_menu_compact = true
     mediaType = "text/markdown"
     isPlainText = true
     baseName = "checklist"
+
+# Add font media types for downloading KaTeX fonts.
+[mediaTypes]
+  [mediaTypes.'font/woff']
+    suffixes = ['woff']
+  [mediaTypes.'font/woff2']
+    suffixes = ['woff2']

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

@@ -87,7 +87,7 @@ Matrix 1.12 is expected to be released in the July-September 2024 calendar quart
 The homeserver SHOULD be able to supply thumbnails for uploaded images
 and videos. The exact file types which can be thumbnailed are not
 currently specified - see [Issue
-\#1938](https://github.com/matrix-org/matrix-doc/issues/1938) for more
+\#1938](https://github.com/matrix-org/matrix-spec/issues/453) for more
 information.
 
 The thumbnail methods are "crop" and "scale". "scale" tries to return an

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

@@ -921,7 +921,7 @@ collaborate to create a common set of translations for all languages.
 
 {{% boxes/note %}}
 Known translations for the emoji are available from
-<https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/>
+<https://github.com/matrix-org/matrix-spec/tree/main/data-definitions/>
 and can be translated online:
 <https://translate.riot.im/projects/matrix-doc/sas-emoji-v1>
 {{% /boxes/note %}}

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

@@ -119,7 +119,7 @@ Clients SHOULD verify the structure of incoming events to ensure that
 the expected keys exist and that they are of the right type. Clients can
 discard malformed events or display a placeholder message to the user.
 Redacted `m.room.message` events MUST be removed from the client. This
-can either be replaced with placeholder text (e.g. "\[REDACTED\]") or
+can either be replaced with placeholder text (e.g. "[REDACTED]") or
 the redacted message can be removed entirely from the messages view.
 
 Events which have attachments (e.g. `m.image`, `m.file`) SHOULD be

content/proposals.md

@@ -408,41 +408,9 @@ development or testing data.
 that a particular MSC works) do not have to follow this process.
 
 1.  Have an idea for a feature.
-1.  Implement the feature using unstable endpoints, vendor prefixes, and
-    unstable feature flags as appropriate.
-    -   When using unstable endpoints, they MUST include a vendor
-        prefix. For example:
-        `/_matrix/client/unstable/com.example/login`. Vendor prefixes
-        throughout Matrix always use the Java package naming convention.
-        The MSC for the feature should identify which preferred vendor
-        prefix is to be used by early adopters.
-    -   Note that unstable namespaces do not automatically inherit
-        endpoints from stable namespaces: for example, the fact that
-        `/_matrix/client/r0/sync` exists does not imply that
-        `/_matrix/client/unstable/com.example/sync` exists.
-    -   If the client needs to be sure the server supports the feature,
-        an unstable feature flag that MUST be vendor prefixed is to be
-        used. This kind of flag shows up in the `unstable_features`
-        section of `/versions` as, for example, `com.example.new_login`.
-        The MSC for the feature should identify which preferred feature
-        flag is to be used by early adopters.
-    -   When using this approach correctly, the implementation can
-        ship/release the feature at any time, so long as the
-        implementation is able to accept the technical debt that results
-        from needing to provide adequate backwards and forwards
-        compatibility. The implementation MUST support the flag (and
-        server-side implementation) disappearing and be generally safe
-        for users. Note that implementations early in the MSC review
-        process may also be required to provide backwards compatibility
-        with earlier editions of the proposal.
-    -   If the implementation cannot support the technical debt (or if
-        it's impossible to provide forwards/backwards compatibility -
-        e.g. a user authentication change which can't be safely rolled
-        back), the implementation should not attempt to implement the
-        feature and should instead wait for a spec release.
-    -   If at any point after early release, the idea changes in a
-        backwards-incompatible way, the feature flag should also change
-        so that implementations can adapt as needed.
+1.  Implement the feature using [unstable endpoints, vendor prefixes, and
+    unstable feature flags](#unstable-endpoints-features-and-vendor-prefixes)
+    as appropriate.
 1.  In parallel, or ahead of implementation, open an MSC and solicit
     review per above.
 1.  Before FCP can be called, the Spec Core Team will require evidence
@@ -452,10 +420,7 @@ that a particular MSC works) do not have to follow this process.
     forwards/backwards compatibility concerns mentioned here.
 1.  The FCP process is completed, and assuming nothing is flagged the
     MSC lands.
-1.  Implementations can now switch to using stable prefixes
-    (for example, for an endpoint, moving from
-    `/unstable/org.matrix.mscxxxx/frobnicate`
-    to `/v1/frobnicate`), assuming that the change
+1.  Implementations can now switch to using stable prefixes, assuming that the change
     is backwards compatible with older implementations. In the rare occasion
     where backwards compatibility is not possible without a new spec release,
     implementations should continue to use unstable prefixes.
@@ -471,13 +436,6 @@ that a particular MSC works) do not have to follow this process.
     started supporting the new spec release, some noise should be raised
     in the general direction of the implementation.
 
-{{% boxes/note %}}
-MSCs MUST still describe what the stable endpoints/feature looks like
-with a note towards the bottom for what the unstable feature
-flag/prefixes are. For example, an MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/
-com.example/new/endpoint`.
-{{% /boxes/note %}}
-
 In summary:
 
 -   Implementations MUST NOT use stable endpoints before the MSC has
@@ -489,14 +447,90 @@ In summary:
 -   Implementations SHOULD be wary of the technical debt they are
     incurring by moving faster than the spec.
 -   The vendor prefix is chosen by the developer of the feature, using
-    the Java package naming convention. The foundation's preferred
-    vendor prefix is `org.matrix`.
+    the Java package naming convention.
 -   The vendor prefixes, unstable feature flags, and unstable endpoints
     should be included in the MSC, though the MSC MUST be written in a
     way that proposes new stable endpoints. Typically this is solved by
     a small table at the bottom mapping the various values from stable
     to unstable.
 
+#### Unstable endpoints, features and vendor prefixes
+
+Unstable endpoints MUST use `/unstable` as the endpoint version and a
+vendor prefix in Java package naming format. For example:
+`/_matrix/client/unstable/com.example.mscxxxx/login`.
+
+{{% boxes/note %}}
+Proposal authors operating with a Matrix.org Foundation mandate SHOULD use
+a vendor prefix within the `org.matrix` namespace. This namespace is otherwise
+restricted. Authors who don't own a domain MAY use the `io.github` namespace
+instead.
+{{% /boxes/note %}}
+
+Note that unstable namespaces do not automatically inherit endpoints from
+stable namespaces: for example, the fact that `/_matrix/client/v3/sync`
+exists does not imply that `/_matrix/client/unstable/com.example.mscxxxx/sync`
+exists.
+
+Vendor prefixes MUST also be used for:
+
+-   New parameters on existing endpoints. For example:
+    `/_matrix/client/v3/publicRooms?com.example.mscxxxx.ordered_by=member_count`.
+-   New properties in existing JSON objects. For example:
+
+    ```json
+    {
+      "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+      "displayname": "Alice Margatroid",
+      "com.example.mscxxxx.phone": [{
+        "type": "landline",
+        "number": "+1-206-555-7000"
+      }],
+      ...
+    }
+    ```
+
+-   New values for existing parameters or properties. For example:
+
+    ```json
+    {
+      "errcode": "COM.EXAMPLE.MSCXXXX.M_INVALID_EMAIL",
+      "error": "The email address you provided is invalid."
+    }
+    ```
+
+If the client needs to be sure the server supports the feature, an
+unstable feature flag that MUST also be vendor prefixed is to be used.
+This flag shows up in the `unstable_features` section of
+[`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
+as, for example, `com.example.mscxxxx.new_login`.
+
+{{% boxes/note %}}
+MSCs MUST still describe what the stable endpoints/feature looks like
+with a note towards the bottom for what the unstable feature
+flag/prefixes are. For example, an MSC would propose `/_matrix/client/v1/new/endpoint`,
+not `/_matrix/client/unstable/com.example.mscxxxx/new/endpoint`.
+{{% /boxes/note %}}
+
+When using this approach correctly, the implementation can release
+the feature at any time, so long as the implementation is able to
+accept the technical debt that results from needing to provide
+adequate backwards and forwards compatibility. The implementation
+MUST support the flag (and server-side implementation) disappearing
+and be generally safe for users. Note that implementations early in
+the MSC review process may also be required to provide backwards
+compatibility with earlier editions of the proposal.
+
+If the implementation cannot support the technical debt (or if it's
+impossible to provide forwards/backwards compatibility - e.g. a user
+authentication change which can't be safely rolled back), the
+implementation should not attempt to implement the feature and should
+instead wait for a spec release.
+
+If at any point after early release, the idea changes in a
+backwards-incompatible way, the feature flag should also change so
+that implementations can adapt as needed.
+
 ### Placeholder MSCs
 
 Some proposals may contain security-sensitive or private context which can't be

data/api/client-server/rooms.yaml

@@ -223,7 +223,7 @@ paths:
             type: string
         # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON
         # filter might be a better alternative.
-        # See https://github.com/matrix-org/matrix-doc/issues/1337
+        # See https://github.com/matrix-org/matrix-doc/issues/1227
         - in: query
           name: membership
           description: |-

data/api/client-server/third_party_lookup.yaml

@@ -78,7 +78,7 @@ paths:
                       },
                       "room": {
                         "regexp": "[^\\s]+\\/[^\\s]+",
-                        "placeholder": "matrix-org/matrix-doc"
+                        "placeholder": "matrix-org/matrix-spec"
                       }
                     },
                     "instances": [

data/api/server-server/openid.yaml

@@ -43,7 +43,12 @@ paths:
                 properties:
                   sub:
                     type: string
-                    description: The Matrix User ID who generated the token.
+                    description: |
+                      The Matrix User ID who generated the token.
+
+                      The caller MUST validate that the returned user ID is on the server they
+                      called (i.e. if you make a request to example.com and it returns
+                      `@alice:matrix.org`, the result is invalid).
                     example: "@alice:example.com"
                 required:
                   - sub

layouts/_markup/render-passthrough.html

@@ -5,15 +5,7 @@
     We use it to send the delimited passthrough element through KaTeX to render maths
     in the Olm / Megolm spec.
 
-    See: https://gohugo.io/functions/transform/tomath/#step-2
+    See: https://www.docsy.dev/docs/content/diagrams-and-formulae/#add-passthrough-render-hook
 
 */ -}}
-{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
-{{- with try (transform.ToMath .Inner $opts) }}
-  {{- with .Err }}
-    {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
-  {{- else }}
-    {{- .Value }}
-    {{- $.Page.Store.Set "hasMath" true }}
-  {{- end }}
-{{- end -}}
+{{ partial "scripts/math.html" . }}

layouts/_partials/breadcrumb.html

@@ -1,28 +1,35 @@
 {{/*
 
-  A copy of the breadcrumb.html partial in Docsy, modified
-	to:
+  A copy of the breadcrumb.html partial in Docsy, modified to:
+
+  * show the breadcrumbs by default by removing the `td-breadcrumbs__single`
+    class
   * omit breadcrumbs when this is the homepage
   * otherwise, include the homepage in the breadcrumbs
 
 */}}
 
-{{ if not .IsHome }}
+{{ if not .IsHome -}}
 <nav aria-label="breadcrumb" class="td-breadcrumbs">
-	<ol class="breadcrumb">
-{{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
-	</ol>
-</nav	>
-{{ end }}
+  <ol class="breadcrumb">
+	{{- template "breadcrumbnav" (dict "p1" . "p2" .) }}
+  </ol>
+</nav>
+{{ end -}}
 
-{{ define "breadcrumbnav" }}
-{{ if .p1.Parent }}
-{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 )  }}
-{{ else if not .p1.IsHome }}
-{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 )  }}
-{{ end }}
-{{ $isActive :=  eq .p1 .p2  }}
-<li class="breadcrumb-item{{ if $isActive }} active{{ end }}" {{ if $isActive }}aria-current="page"{{ end }}>
-	<a href="{{ .p1.RelPermalink }}">{{ .p1.LinkTitle }}</a>
-</li>
-{{ end }}
+{{- define "breadcrumbnav" -}}
+  {{ if .p1.Parent -}}
+    {{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 )  -}}
+  {{ else if not .p1.IsHome -}}
+    {{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 )  -}}
+  {{ end -}}
+  {{ $isActive :=  eq .p1 .p2  }}
+  <li class="breadcrumb-item{{ if $isActive }} active{{ end }}"
+      {{- if $isActive }}aria-current="page"{{ end }}>
+    {{ if $isActive -}}
+      {{ .p1.LinkTitle -}}
+    {{ else -}}
+      <a href="{{ .p1.RelPermalink }}">{{ .p1.LinkTitle }}</a>
+    {{- end -}}
+  </li>
+{{- end -}}

layouts/_partials/navbar.html

@@ -1,8 +1,11 @@
 {{- /*
 
-  A version of the navbar.html partial in Docsy, only modified
-	to include the spec version, which is calculated using an
-  inline `version-string` partial.
+  A copy of the navbar.html partial in Docsy, modified to:
+
+  * remove `data-bs-theme` at L20, otherwise the title disappears on hover.
+  * replace the site title with "specification" at L31.
+  * include the spec version from the config at L34-35, which is calculated
+    using an inline `version-string` partial.
 
 */ -}}
 
@@ -13,8 +16,8 @@
 {{ $baseURL := urls.Parse $.Site.Params.Baseurl -}}
 
 <nav class="td-navbar js-navbar-scroll
-            {{- if $cover }} td-navbar-cover {{- end }}" data-bs-theme="light">
-<div class="container-fluid flex-column flex-md-row">
+            {{- if $cover }} td-navbar-cover {{- end }}">
+<div class="td-navbar-container container-fluid flex-column flex-md-row">
   <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}">
     {{- /**/ -}}
     <span class="navbar-brand__logo navbar-logo">
@@ -32,7 +35,8 @@
 	  <span class="navbar-version"> &mdash; {{ partial "version-string" . }}</span>
     {{- /**/ -}}
   </a>
-  <div class="td-navbar-nav-scroll ms-md-auto" id="main_navbar">
+  <div class="td-navbar-nav-scroll td-navbar-nav-scroll--indicator" id="main_navbar">
+    <div class="scroll-indicator scroll-left"></div>
     <ul class="navbar-nav">
       {{ $p := . -}}
       {{ range .Site.Menus.main -}}
@@ -58,39 +62,41 @@
       </li>
       {{ end -}}
       {{ if .Site.Params.versions -}}
-      <li class="nav-item dropdown d-none d-lg-block">
+      <li class="nav-item dropdown d-none d-lg-block td-navbar__version-menu">
         {{ partial "navbar-version-selector.html" . -}}
       </li>
       {{ end -}}
       {{ if (gt (len .Site.Home.Translations) 0) -}}
-      <li class="nav-item dropdown d-none d-lg-block">
+      <li class="nav-item td-navbar__lang-menu">
         {{ partial "navbar-lang-selector.html" . -}}
       </li>
       {{ end -}}
-      {{ if .Site.Params.ui.showLightDarkModeMenu -}}
-      <li class="td-light-dark-menu nav-item dropdown">
+      {{- $darkMode := partialCached "dark-mode-config.html" "dark-mode-global" -}}
+      {{ if $darkMode.showMenu -}}
+      <li class="nav-item td-navbar__light-dark-menu">
         {{ partial "theme-toggler" . }}
       </li>
       {{ end -}}
     </ul>
+    <div class="scroll-indicator scroll-right"></div>
   </div>
-  <div class="d-none d-lg-block">
+  <div class="d-none d-lg-block td-navbar__search">
     {{ partial "search-input.html" . }}
   </div>
 </div>
 </nav>
 
-{{ define "_partials/version-string" }}
-    {{ $ret := "unstable version"}}
+{{- define "_partials/version-string" -}}
+    {{ $ret := "unstable version" -}}
 
-    {{ $status := .Site.Params.version.status }}
+    {{ $status := .Site.Params.version.status -}}
 
-    {{ if ne $status "unstable"}}
-        {{ $path := path.Join "changelogs" }}
+    {{ if ne $status "unstable" -}}
+        {{ $path := path.Join "changelogs" -}}
 
-        {{/* produces a string similar to "version v1.5" */}}
-        {{ $ret = delimit (slice "version v" .Site.Params.version.major "." .Site.Params.version.minor) "" }}
-    {{ end }}
+        {{/* produces a string similar to "version v1.5" */ -}}
+        {{ $ret = delimit (slice "version v" .Site.Params.version.major "." .Site.Params.version.minor) "" -}}
+    {{ end -}}
 
-    {{ return $ret }}
-{{ end }}
+    {{ return $ret -}}
+{{- end -}}

layouts/_partials/sidebar-tree.html

@@ -1,37 +1,57 @@
 {{- /*
 
-  A modified version of the siderbar-tree.html partial in Docsy, adding:
-  
-  * The "toc.html" partial at L45.
+  A copy of the siderbar-tree.html partial in Docsy, modified to:
+
+  * Ignore the `sidebarRoot` parameter, because of this regression:
+    <https://github.com/google/docsy/issues/2426>
+  * Add the "toc.html" partial at L68.
 
 */ -}}
 
-{{/* We cache this partial for bigger sites and set the active class client side. */ -}}
-{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}}
-{{ $shouldDelayActive := ge (len .Site.Pages) $sidebarCacheLimit -}}
+{{ $context := .context -}}
+{{ $sidebarRoot := .sidebarRoot -}}
+{{ $sidebarRootID := .sidebarRootID -}}
+{{ $cacheSidebar := .cacheSidebar -}}
+
+{{ with $context -}}
+{{/* When the sidebar is cached, "active" class is set client side. */ -}}
+{{ $shouldDelayActive := $cacheSidebar -}}
+
 <div id="td-sidebar-menu" class="td-sidebar__inner{{ if $shouldDelayActive }} d-none{{ end }}">
   {{ if not .Site.Params.ui.sidebar_search_disable -}}
+
   <form class="td-sidebar__search d-flex align-items-center">
     {{ partial "search-input.html" . }}
-    <button class="btn btn-link td-sidebar__toggle d-md-none p-0 ms-3 fas fa-bars" type="button" data-bs-toggle="collapse" data-bs-target="#td-section-nav" aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
+    <button class="btn btn-link td-sidebar__toggle" type="button" {{/**/ -}}
+      data-bs-toggle="collapse" data-bs-target="#td-section-nav" {{/**/ -}}
+      aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
     </button>
   </form>
-  {{ else -}}
+
+  {{- else -}}
+
   <div id="content-mobile">
   <form class="td-sidebar__search d-flex align-items-center">
     {{ partial "search-input.html" . }}
-    <button class="btn btn-link td-sidebar__toggle d-md-none p-0 ms-3 fas fa-bars" type="button" data-bs-toggle="collapse" data-bs-target="#td-section-nav" aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
+    <button class="btn btn-link td-sidebar__toggle" type="button" {{/**/ -}}
+      data-bs-toggle="collapse" data-bs-target="#td-section-nav" {{/**/ -}}
+      aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
     </button>
   </form>
   </div>
   <div id="content-desktop"></div>
-  {{ end -}}
+
+  {{- end }}
+  {{/* */ -}}
+
   <nav class="td-sidebar-nav collapse
-      {{- if .Site.Params.ui.sidebar_search_disable }} td-sidebar-nav--search-disabled{{ end -}}
-      {{- if .Site.Params.ui.sidebar_menu_foldable }} foldable-nav{{ end -}}
-      " id="td-section-nav">
-    {{ if  (gt (len .Site.Home.Translations) 0) -}}
-    <div class="td-sidebar-nav__section nav-item dropdown d-block d-lg-none">
+        {{- if .Site.Params.ui.sidebar_search_disable }} td-sidebar-nav--search-disabled{{ end -}}
+        {{- if .Site.Params.ui.sidebar_menu_foldable }} foldable-nav{{ end }}" {{/**/ -}}
+      id="td-section-nav"
+      {{- if .Site.Params.ui.sidebar_root_enabled }} data-sidebar-root-id="{{ $sidebarRootID }}"{{ end -}}
+    >
+    {{ if and .Site.Params.ui.sidebar_lang_menu (gt (len .Site.Home.Translations) 0) -}}
+    <div class="td-sidebar-nav__section nav-item d-block d-lg-none">
       {{ partial "navbar-lang-selector.html" . }}
     </div>
     {{ end -}}
@@ -45,44 +65,129 @@
     {{ partial "toc.html" . }}
   </nav>
 </div>
+
+{{- end }}{{/* with $context */ -}}
+
 {{ define "section-tree-nav-section" -}}
-{{ $s := .section -}}
-{{ $p := .page -}}
-{{ $shouldDelayActive := .shouldDelayActive -}}
-{{ $sidebarMenuTruncate := .sidebarMenuTruncate -}}
-{{ $treeRoot := cond (eq .ulNr 0) true false -}}
-{{ $ulNr := .ulNr -}}
-{{ $ulShow := .ulShow -}}
-{{ $active := and (not $shouldDelayActive) (eq $s $p) -}}
-{{ $activePath := and (not $shouldDelayActive) (or (eq $p $s) ($p.IsDescendant $s)) -}}
-{{ $show := cond (or (lt $ulNr $ulShow) $activePath (and (not $shouldDelayActive) (eq $s.Parent $p.Parent)) (and (not $shouldDelayActive) (eq $s.Parent $p)) (not $p.Site.Params.ui.sidebar_menu_compact) (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))) true false -}}
-{{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}}
-{{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}}
-{{ $pages := $pages_tmp | first $sidebarMenuTruncate -}}
-{{ $truncatedEntryCount := sub (len $pages_tmp) $sidebarMenuTruncate -}}
-{{ if gt $truncatedEntryCount 0 -}}
-  {{ warnf "WARNING: %d sidebar entries have been truncated. To avoid this, increase `params.ui.sidebar_menu_truncate` to at least %d (from %d) in your config file. Section: %s"
-      $truncatedEntryCount (len $pages_tmp) $sidebarMenuTruncate  $s.Path -}}
-{{ end -}}
-{{ $withChild := gt (len $pages) 0 -}}
-{{ $manualLink := cond (isset $s.Params "manuallink") $s.Params.manualLink ( cond (isset $s.Params "manuallinkrelref") (relref $s $s.Params.manualLinkRelref) $s.RelPermalink) -}}
-{{ $manualLinkTitle := cond (isset $s.Params "manuallinktitle") $s.Params.manualLinkTitle $s.Title -}}
-<li class="td-sidebar-nav__section-title td-sidebar-nav__section{{ if $withChild }} with-child{{ else }} without-child{{ end }}{{ if $activePath }} active-path{{ end }}{{ if (not (or $show $p.Site.Params.ui.sidebar_menu_foldable )) }} collapse{{ end }}" id="{{ $mid }}-li">
-  {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}}
-  <input type="checkbox" id="{{ $mid }}-check"{{ if $activePath}} checked{{ end }}/>
-  <label for="{{ $mid }}-check"><a href="{{ $manualLink }}"{{ if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end }}{{ with $s.Params.manualLinkTarget }} target="{{ . }}"{{ if eq . "_blank" }} rel="noopener"{{ end }}{{ end }} class="align-left ps-0 {{ if $active}} active{{ end }} td-sidebar-link{{ if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}{{ if $treeRoot }} tree-root{{ end }}" id="{{ $mid }}">{{ with $s.Params.Icon}}<i class="{{ . }}"></i>{{ end }}<span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">{{ $s.LinkTitle }}</span></a></label>
-  {{ else -}}
-  <a href="{{ $manualLink }}"{{ if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end }}{{ with $s.Params.manualLinkTarget }} target="{{ . }}"{{ if eq . "_blank" }} rel="noopener"{{ end }}{{ end }} class="align-left ps-0{{ if $active}} active{{ end }} td-sidebar-link{{ if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}{{ if $treeRoot }} tree-root{{ end }}" id="{{ $mid }}">{{ with $s.Params.Icon}}<i class="{{ . }}"></i>{{ end }}<span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">{{ $s.LinkTitle }}</span></a>
-  {{- end }}
-  {{- if $withChild }}
-  {{- $ulNr := add $ulNr 1 }}
-  <ul class="ul-{{ $ulNr }}{{ if (gt $ulNr 1)}} foldable{{end}}">
-    {{ range $pages -}}
-    {{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true))) -}}
-    {{ template "section-tree-nav-section" (dict "page" $p "section" . "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow) }}
+  {{/* cSpell:ignore manuallink manuallinkrelref manuallinktitle */ -}}
+  {{ $s := .section -}}
+  {{ $p := .page -}}
+  {{ $shouldDelayActive := .shouldDelayActive -}}
+  {{ $sidebarMenuTruncate := .sidebarMenuTruncate -}}
+  {{ $treeRoot := cond (eq .ulNr 0) true false -}}
+  {{ $ulNr := .ulNr -}}
+  {{ $ulShow := .ulShow -}}
+  {{ $active := and (not $shouldDelayActive) (eq $s $p) -}}
+  {{ $activePath := and (not $shouldDelayActive) (or (eq $p $s) ($p.IsDescendant $s)) -}}
+  {{ $show := cond
+        (or
+          (lt $ulNr $ulShow)
+          $activePath
+          (and (not $shouldDelayActive) (eq $s.Parent $p.Parent))
+          (and (not $shouldDelayActive) (eq $s.Parent $p))
+          (not $p.Site.Params.ui.sidebar_menu_compact)
+          (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))
+        )
+        true false
+  -}}
+  {{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}}
+  {{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}}
+  {{ $pages := $pages_tmp | first $sidebarMenuTruncate -}}
+  {{ $truncatedEntryCount := sub (len $pages_tmp) $sidebarMenuTruncate -}}
+
+  {{ if gt $truncatedEntryCount 0 -}}
+    {{ warnf "WARNING: %d sidebar entries have been truncated. To avoid this, increase `params.ui.sidebar_menu_truncate` to at least %d (from %d) in your config file. Section: %s"
+        $truncatedEntryCount (len $pages_tmp) $sidebarMenuTruncate  $s.Path -}}
+  {{ end -}}
+
+  {{ $withChild := gt (len $pages) 0 -}}
+  {{ $manualLink :=
+      cond
+        (isset $s.Params "manuallink")
+        $s.Params.manualLink
+        (cond
+          (isset $s.Params "manuallinkrelref")
+          (relref $s $s.Params.manualLinkRelref)
+          $s.RelPermalink
+        )
+  -}}
+  {{ $manualLinkTitle :=
+      cond
+        (isset $s.Params "manuallinktitle")
+        $s.Params.manualLinkTitle
+        $s.Title
+  -}}
+  {{ if and $treeRoot (eq $s.Params.sidebar_root_for "self") -}}
+    {{ with $s.Parent -}}
+      {{ $manualLink = .RelPermalink -}}
+    {{ end -}}
+  {{ end -}}
+  <li class="td-sidebar-nav__section-title td-sidebar-nav__section
+        {{- if $withChild }} with-child{{ else }} without-child{{ end -}}
+        {{ if $activePath }} active-path{{ end -}}
+        {{ if (not (or $show $p.Site.Params.ui.sidebar_menu_foldable )) }} collapse{{ end -}}
+      " {{/**/ -}}
+      id="{{ $mid }}-li" {{- /**/ -}}
+    >
+    {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}}
+    <input type="checkbox" id="{{ $mid }}-check"{{ if $activePath}} checked{{ end }}/>
+    <label for="{{ $mid }}-check">{{/**/ -}}
+      <a href="{{ $manualLink }}"
+        {{- if ne $s.LinkTitle $manualLinkTitle }} {{/**/ -}}
+          title="{{ $manualLinkTitle }}"
+        {{- end -}}
+        {{ with $s.Params.manualLinkTarget }} {{/**/ -}}
+          target="{{ . }}"
+          {{- if eq . "_blank" }} rel="noopener"{{ end -}}
+        {{ end }} {{/**/ -}}
+        class="align-left ps-0 {{ if $active}} active{{ end }} td-sidebar-link
+          {{- if $s.IsPage }} td-sidebar-link__page
+          {{- else }} td-sidebar-link__section
+          {{- end }}
+          {{- if $treeRoot }} tree-root{{ end }}" {{/**/ -}}
+        id="{{ $mid }}" {{- /**/ -}}
+      >
+        {{- with $s.Params.Icon -}}
+          <i class="{{ . }}"></i>
+        {{- end -}}
+        <span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">
+          {{- $s.LinkTitle -}}
+        </span> {{- /**/ -}}
+      </a> {{- /**/ -}}
+    </label>
+    {{ else -}}
+      <a href="{{ $manualLink }}"
+        {{- if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end -}}
+        {{ with $s.Params.manualLinkTarget }} {{/**/ -}}
+          target="{{ . }}"
+          {{- if eq . "_blank" }} rel="noopener"{{ end -}}
+        {{ end }} {{/**/ -}}
+        class="align-left ps-0
+          {{- if $active}} active{{ end }} {{/**/ -}}
+          td-sidebar-link
+          {{- if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}
+          {{- if $treeRoot }} tree-root{{ end }}" {{/**/ -}}
+        id="{{ $mid }}" {{- /**/ -}}
+      >
+      {{- with $s.Params.Icon -}}
+        <i class="{{ . }}"></i>
+      {{- end -}}
+      <span class="
+        {{- if $active }}td-sidebar-nav-active-item{{ end -}}
+        {{- if and $s.Params.sidebar_root_for site.Params.ui.sidebar_root_enabled }} td-sidebar-root-up-icon{{ end -}}
+      ">
+        {{- $s.LinkTitle -}}
+      </span></a>
+    {{- end -}}
+    {{ if $withChild -}}
+    {{ $ulNr := add $ulNr 1 }}
+    <ul class="ul-{{ $ulNr }}{{ if (gt $ulNr 1)}} foldable{{end}}">
+      {{ range $pages -}}
+        {{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true))) -}}
+          {{ template "section-tree-nav-section" (dict "page" $p "section" . "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow) }}
+        {{- end }}
+      {{- end }}
+    </ul>
     {{- end }}
-    {{- end }}
-  </ul>
-  {{- end }}
-</li>
-{{- end -}}
+  </li>
+{{- end }}

layouts/_partials/toc.html

@@ -1,15 +1,29 @@
 {{/*
 
-  A modified version of the toc.html partial in Docsy.
+  A copy of the toc.html partial in Docsy, modified to:
 
-*/}}
-{{ $page := .Params }}
+  * show the page's title instead of "on this page"
+
+*/ -}}
+
+{{/*
+
+  Always render the td-toc element. ScrollSpy is counting on it to exist,
+  even if it's empty.
+
+  cSpell:ignore notoc
+*/ -}}
+
+<div class="td-toc" data-proofer-ignore>
 {{ if not .Params.notoc -}}
-  {{ with .TableOfContents -}}
-    <hr>
-    <div id="toc">
-        <a id="toc-title" href="#">{{ $page.Title }}</a>
-        {{ . }}
+  {{ $toc := .TableOfContents -}}
+  {{ if and $toc (ne $toc `<nav id="TableOfContents"></nav>`) -}}
+    <div class="td-toc-title">
+      <span class="td-toc-title__text">{{ .Params.Title }}</span>
+      <a class="td-toc-title__link" title="{{ i18n "toc_top_of_page" }}" href="#"></a>
     </div>
+    {{ $toc | safeHTML }}
   {{ end -}}
 {{ end -}}
+</div>
+{{/* */ -}}

layouts/docs/baseof.html

@@ -1,11 +1,14 @@
 {{/*
 
-  A copy of the baseof.html partial in Docsy, modified
-	to remove the right-hand column from the layout.
+  A copy of the baseof.html partial in Docsy, modified to:
 
-*/}}
+  * generate a static file `versions.json` that can be used to populate the
+    version picker.
+  * remove the right-hand column from the layout.
 
-{{/* Generate a static file versions.json that can be used to populate the version picker */}}
+*/ -}}
+
+{{/* Generate a static file versions.json that can be used to populate the version picker */ -}}
 {{ if .IsHome }}
   {{- /* Load all changelog subpages, sorted by release date */ -}}
   {{ $changelog := site.GetPage "changelog" }}
@@ -28,20 +31,18 @@
 <html itemscope itemtype="http://schema.org/WebPage"
     {{- with .Site.Language.LanguageDirection }} dir="{{ . }}" {{- end -}}
     {{ with .Site.Language.Lang }} lang="{{ . }}" {{- end }} {{/**/ -}}
-    class="no-js">
+    class="no-js"
+    {{- $darkMode := partialCached "dark-mode-config.html" "dark-mode-global" -}}
+    {{- if $darkMode.enable }} data-theme-init{{ end }}>
   <head>
     {{ partial "head.html" . }}
-    {{ if .Page.Store.Get "hasMath" }}
-      <link href="{{ relURL "css/katex.min.css" }}" rel="preload" as="style">
-      <link href="{{ relURL "css/katex.min.css" }}" rel="stylesheet">
-    {{ end }}
   </head>
   <body class="td-{{ .Kind }}{{ with .Page.Params.body_class }} {{ . }}{{ end }}">
     <header>
       {{ partial "navbar.html" . }}
     </header>
     <div class="container-fluid td-outer">
-      <div class="td-main">
+      <div class="td-main" {{- partialCached "td/scrollspy-attr.txt" . .Section | safeHTMLAttr }}>
         <div class="row flex-xl-nowrap">
           <aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
             {{ partial "sidebar.html" . }}

meta/releasing.md

@@ -50,11 +50,6 @@ First, can we even release the spec? This stage is mostly preparation work neede
 to ensure a consistent and reliable specification.
 
 1. Ensure `main` is committed with all the spec changes you expect to be there.
-2. Review the changelog to look for typos, wording inconsistencies, or lines which
-   can be merged. For example, "Fix typos" and "Fix spelling" can be condensed to
-   "Fix various typos throughout the specification".
-3. Do a quick skim to ensure changelogs reference the MSCs which brought the changes
-   in. They should be linked to the GitHub MSC PR (not the markdown document).
 
 ## The release
 
@@ -79,20 +74,24 @@ release.
    2. Run `./scripts/generate-changelog.sh v1.2` (using the correct version number).
       The script will use the current date. If that date is wrong, correct the document
       by using the same `YYYY-MM-DD` date format.
-   3. Commit the result.
+   3. Review the changelog to look for typos, wording inconsistencies, or lines which
+      can be merged. For example, "Fix typos" and "Fix spelling" can be condensed to
+      "Fix various typos throughout the specification".
+   4. Do a quick skim to ensure changelogs reference the MSCs which brought the changes
+      in. They should be linked to the GitHub MSC PR (not the markdown document).
+   5. Commit the result.
+   6. Now is a good time to have someone else review the changelog.
 5. Tag the branch with the spec release with a format of `v1.2` (if releasing Matrix 1.2).
 6. Push the release branch and the tag.
 7. GitHub Actions will run its build steps. Wait until these are successful. If fixes
    need to be made to repair the pipeline or spec build, delete and re-tag the release.
    You may need to fix up the changelog file by hand in this case.
-8. Check out and fast-forward `main` to the release branch.
-9. Create a new release on GitHub from the newly created tag.
-   * The title should be just "v1.2" (for example).
-   * The description should be a copy/paste of the changelog. The generated changelog
-     will be at `content/changelog/v1.2.md` - copy/paste verbatim.
-   * Upload the artifacts of the GitHub Actions build for the release to the GitHub
-     release as artifacts themselves. This should be the tarball that will be deployed
-     to spec.matrix.org.
+8. GitHub Actions should have drafted a release based on the new tag. Find it
+   at https://github.com/matrix-org/matrix-spec/releases.
+   1. Double-check the generated release notes, and check that `spec-artifact.zip` and
+      `spec-historical-artifact.zip` are both attached to the draft release.
+   2. Publish the draft release.
+9. Check out and fast-forward `main` to the release branch.
 10. Commit a reversion to `params.version` of `./config/_default/hugo.toml` on `main`:
     ```toml
     [params.version]
@@ -103,7 +102,8 @@ release.
     ```
 11. Push pending commits and ensure the unstable spec updates accordingly from the
     GitHub Actions pipeline.
-12. Deploy the release on the webserver. See internal wiki.
+12. Deploy the release on the webserver. See "Spec release process" in the
+    internal handbook.
 
 ## Patching a release
 

scripts/download-katex-assets.sh

@@ -1,41 +0,0 @@
-#!/bin/bash
-#
-# Download the KaTeX fonts and CSS, and copy them into `static`.
-set -e
-
-root=$(dirname "$0")/..
-
-# Check that the caller supplied a version.
-version=$1
-if [[ -z $1 || $1 = "-h" || $1 = "--help" ]]; then
-    >&2 echo "Usage: download-katex-assets.sh VERSION (e.g. v0.16.23)"
-    >&2 echo
-    >&2 echo "Downloads KaTeX fonts and CSS from the specified release"
-    >&2 echo "on GitHub and puts the files into static/."
-    exit 1
-fi
-
-# Create a temporary directory and register a handler to clean it up on exit.
-tmp_dir=$(mktemp -d)
-clean_up () {
-    rm -rf "$tmp_dir"
-} 
-trap clean_up EXIT
-
-# Fetch the release archive.
-archive=$tmp_dir/katex.tar.gz
-url=https://github.com/KaTeX/KaTeX/releases/download/$version/katex.tar.gz
-echo "GET $url"
-curl -L --output "$archive" "$url"
-
-# Unpack the archive.
-tar -xzvf "$archive" -C "$tmp_dir"
-
-# Move the CSS file into place.
-install -vm644 "$tmp_dir/katex/katex.min.css" "$root/static/css/katex.min.css"
-
-# Remove any existing fonts and move the new ones into place.
-rm -rvf "$root"/static/css/fonts/KaTeX*
-while IFS= read -r -d '' file; do
-    install -vm644 "$file" "$root/static/css/fonts"
-done < <(find "$tmp_dir/katex/fonts" -maxdepth 1 -name "KaTeX*.woff2" -print0)

scripts/proposals.js

@@ -6,7 +6,7 @@
  * in the specification.
  *
  * In detail, it:
- * - fetches all GitHub issues from matrix-doc that have the `proposal` label
+ * - fetches all GitHub issues from matrix-spec-proposals that have the `proposal` label
  * - groups them by their state in the MSC process
  * - does some light massaging of them so it's easier for the Hugo template to work with them
  * - store them at /data/msc