Merge 16b98e9097 into 2a3841347e

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

.github/workflows/main.yml

@@ -1,8 +1,9 @@
 name: "Spec"
 
 env:
-  HUGO_VERSION: 0.148.1
+  HUGO_VERSION: 0.153.3
   PYTHON_VERSION: 3.13
+  NODE_VERSION: 24
 
 on:
   push:
@@ -27,7 +28,7 @@ jobs:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: ${{ env.NODE_VERSION }}
       - name: "🔎 Run validator"
         run: |
           npx @redocly/cli@latest lint data/api/*/*.yaml
@@ -201,7 +202,7 @@ jobs:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: ${{ env.NODE_VERSION }}
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
@@ -288,7 +289,7 @@ jobs:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: ${{ env.NODE_VERSION }}
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:

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

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

changelogs/identity_service/newsfragments/2277.clarification

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

changelogs/internal/newsfragments/2287.clarification

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

changelogs/server_server/newsfragments/2191.clarification

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

config/_default/hugo.toml

@@ -166,3 +166,11 @@ sidebar_menu_compact = true
     mediaType = "text/markdown"
     isPlainText = true
     baseName = "checklist"
+
+# Add font media types for downloading KaTeX fonts.
+# See: https://www.docsy.dev/docs/content/diagrams-and-formulae/#create-media-types-for-katex-fonts
+[mediaTypes]
+  [mediaTypes.'font/woff']
+    suffixes = ['woff']
+  [mediaTypes.'font/woff2']
+    suffixes = ['woff2']

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

@@ -24,16 +24,23 @@ properties:
   submit_url:
     type: string
     format: uri
+    x-changedInMatrixVersion:
+      "1.18": |-
+        The URL has the same request and response parameters and error codes as
+        the Identity Service API's endpoint.
     description: |-
       An optional field containing a URL where the client must submit the
-      validation token to, with identical parameters to the Identity Service
-      API's `POST /validate/email/submitToken` endpoint (without the requirement
-      for an access token). The homeserver must send this token to the user (if
-      applicable), who should then be prompted to provide it to the client.
+      validation token, with identical request and response parameters and error
+      codes to the Identity Service API's
+      [`POST /validate/email/submitToken`](/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)
+      and [`POST /validate/msisdn/submitToken`](/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)
+      endpoints (without the requirement for an access token). The homeserver
+      must send this token to the user (if applicable), who should then be
+      prompted to provide it to the client.
 
       If this field is not present, the client can assume that verification
       will happen without the client's involvement provided the homeserver
-      advertises this specification version in the `/versions` response
-      (ie: r0.5.0).
+      advertises a sufficiently recent version in the [`GET /versions`](/client-server-api/#get_matrixclientversions)
+      response (ie: r0.5.0).
     example: "https://example.org/path/to/submitToken"
 required: ['sid']

data/api/identity/v2_email_associations.yaml

@@ -153,6 +153,24 @@ paths:
                   value: {
                     "success": true
                   }
+        "400":
+          description: |
+            An error occurred. Some possible errors are:
+
+            - {{% added-in v="1.18" %}} `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is
+              incorrect.
+            - {{% added-in v="1.18" %}} `M_INVALID_PARAM`: One of the supplied parameters is not valid.
+            - {{% added-in v="1.18" %}} `M_SESSION_EXPIRED`: The validation session in question has expired.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOKEN_INCORRECT",
+                    "error": "The token is incorrect"
+                  }
         "403":
           description: |
             The user must do something in order to use this endpoint. One example

data/api/identity/v2_phone_associations.yaml

@@ -155,6 +155,24 @@ paths:
                   value: {
                     "success": true
                   }
+        "400":
+          description: |
+            An error occurred. Some possible errors are:
+
+            - {{% added-in v="1.18" %}} `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is
+              incorrect.
+            - {{% added-in v="1.18" %}} `M_INVALID_PARAM`: One of the supplied parameters is not valid.
+            - {{% added-in v="1.18" %}} `M_SESSION_EXPIRED`: The validation session in question has expired.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOKEN_INCORRECT",
+                    "error": "The token is incorrect"
+                  }
         "403":
           description: |
             The user must do something in order to use this endpoint. One example

data/api/server-server/keys_query.yaml

@@ -34,10 +34,10 @@ paths:
         - in: query
           name: minimum_valid_until_ts
           description: |-
-            A millisecond POSIX timestamp in milliseconds indicating when the returned
-            certificates will need to be valid until to be useful to the requesting server.
+            A millisecond POSIX timestamp. The returned keys SHOULD be valid
+            until at least this timestamp.
 
-            If not supplied, the current time as determined by the notary server is used.
+            If not supplied, the notary server SHOULD use the current time.
           required: false
           example: 1234567890
           schema:
@@ -98,12 +98,11 @@ paths:
                           type: integer
                           format: int64
                           description: |-
-                            A millisecond POSIX timestamp in milliseconds indicating when
-                            the returned certificates will need to be valid until to be
-                            useful to the requesting server.
+                            A millisecond POSIX timestamp. The returned keys
+                            SHOULD be valid until at least this timestamp.
 
-                            If not supplied, the current time as determined by the notary
-                            server is used.
+                            If not supplied, the notary server SHOULD use the
+                            current time.
                           example: 1234567890
               required:
                 - server_keys

go.mod

@@ -2,4 +2,4 @@ module github.com/matrix-org/matrix-spec
 
 go 1.12
 
-require github.com/matrix-org/docsy v0.0.0-20250722140156-5df72519f5af // indirect
+require github.com/matrix-org/docsy v0.0.0-20260106184755-71d103ebb20a // indirect

go.sum

@@ -1,4 +1,4 @@
 github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
-github.com/matrix-org/docsy v0.0.0-20250722140156-5df72519f5af h1:XghgUC0H5BoGrvtT9/oWBUi+5Zux875qRHhpAZ0RURI=
-github.com/matrix-org/docsy v0.0.0-20250722140156-5df72519f5af/go.mod h1:4/t21g/nPraob/DVMm3jrk26k0CDL5I7Mxf+ar0IAgs=
-github.com/twbs/bootstrap v5.3.6+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
+github.com/matrix-org/docsy v0.0.0-20260106184755-71d103ebb20a h1:WB3unuZJy7ewAf33sxbtEwYnC+i+Jt1sJpAR3BtzvEo=
+github.com/matrix-org/docsy v0.0.0-20260106184755-71d103ebb20a/go.mod h1:mdn1m5HJug6ZddQgrOyCrXNegbtdl5evHiqqbEQLzdI=
+github.com/twbs/bootstrap v5.3.8+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

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" . }}

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)