Merge f5c1b24bd8 into fa78688f57

.github/workflows/main.yml

@@ -1,9 +1,8 @@
 name: "Spec"
 
 env:
-  HUGO_VERSION: 0.153.3
+  HUGO_VERSION: 0.148.1
   PYTHON_VERSION: 3.13
-  NODE_VERSION: 24
 
 on:
   push:
@@ -28,7 +27,7 @@ jobs:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version: '20'
       - name: "🔎 Run validator"
         run: |
           npx @redocly/cli@latest lint data/api/*/*.yaml
@@ -202,7 +201,7 @@ jobs:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version: '20'
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
@@ -289,7 +288,7 @@ jobs:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v4
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version: '20'
       - 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("#TableOfContents a");
+  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.
@@ -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("#TableOfContents a.active");
+  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(`#TableOfContents a[href="#${id}"]`);
+  const newEntry = document.querySelector(`#toc nav a[href="#${id}"]`);
   if (!newEntry) {
     console.error("ToC entry not found for ID:", id);
     return;

assets/scss/_styles_project.scss

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

changelogs/internal/newsfragments/2287.clarification

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

config/_default/hugo.toml

@@ -166,11 +166,3 @@ 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']

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-20260106184755-71d103ebb20a // indirect
+require github.com/matrix-org/docsy v0.0.0-20250722140156-5df72519f5af // 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-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=
+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=

layouts/_markup/render-passthrough.html

@@ -5,7 +5,15 @@
     We use it to send the delimited passthrough element through KaTeX to render maths
     in the Olm / Megolm spec.
 
-    See: https://www.docsy.dev/docs/content/diagrams-and-formulae/#add-passthrough-render-hook
+    See: https://gohugo.io/functions/transform/tomath/#step-2
 
 */ -}}
-{{ partial "scripts/math.html" . }}
+{{- $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 -}}

layouts/_partials/breadcrumb.html

@@ -1,35 +1,28 @@
 {{/*
 
-  A copy of the breadcrumb.html partial in Docsy, modified to:
-
-  * show the breadcrumbs by default by removing the `td-breadcrumbs__single`
-    class
+  A copy of the breadcrumb.html partial in Docsy, modified
+	to:
   * 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 }}>
-    {{ if $isActive -}}
-      {{ .p1.LinkTitle -}}
-    {{ else -}}
-      <a href="{{ .p1.RelPermalink }}">{{ .p1.LinkTitle }}</a>
-    {{- end -}}
-  </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 }}>
+	<a href="{{ .p1.RelPermalink }}">{{ .p1.LinkTitle }}</a>
+</li>
+{{ end }}

layouts/_partials/navbar.html

@@ -1,11 +1,8 @@
 {{- /*
 
-  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.
+  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.
 
 */ -}}
 
@@ -16,8 +13,8 @@
 {{ $baseURL := urls.Parse $.Site.Params.Baseurl -}}
 
 <nav class="td-navbar js-navbar-scroll
-            {{- if $cover }} td-navbar-cover {{- end }}">
-<div class="td-navbar-container container-fluid flex-column flex-md-row">
+            {{- if $cover }} td-navbar-cover {{- end }}" data-bs-theme="light">
+<div class="container-fluid flex-column flex-md-row">
   <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}">
     {{- /**/ -}}
     <span class="navbar-brand__logo navbar-logo">
@@ -35,8 +32,7 @@
 	  <span class="navbar-version"> &mdash; {{ partial "version-string" . }}</span>
     {{- /**/ -}}
   </a>
-  <div class="td-navbar-nav-scroll td-navbar-nav-scroll--indicator" id="main_navbar">
-    <div class="scroll-indicator scroll-left"></div>
+  <div class="td-navbar-nav-scroll ms-md-auto" id="main_navbar">
     <ul class="navbar-nav">
       {{ $p := . -}}
       {{ range .Site.Menus.main -}}
@@ -62,41 +58,39 @@
       </li>
       {{ end -}}
       {{ if .Site.Params.versions -}}
-      <li class="nav-item dropdown d-none d-lg-block td-navbar__version-menu">
+      <li class="nav-item dropdown d-none d-lg-block">
         {{ partial "navbar-version-selector.html" . -}}
       </li>
       {{ end -}}
       {{ if (gt (len .Site.Home.Translations) 0) -}}
-      <li class="nav-item td-navbar__lang-menu">
+      <li class="nav-item dropdown d-none d-lg-block">
         {{ partial "navbar-lang-selector.html" . -}}
       </li>
       {{ end -}}
-      {{- $darkMode := partialCached "dark-mode-config.html" "dark-mode-global" -}}
-      {{ if $darkMode.showMenu -}}
-      <li class="nav-item td-navbar__light-dark-menu">
+      {{ if .Site.Params.ui.showLightDarkModeMenu -}}
+      <li class="td-light-dark-menu nav-item dropdown">
         {{ partial "theme-toggler" . }}
       </li>
       {{ end -}}
     </ul>
-    <div class="scroll-indicator scroll-right"></div>
   </div>
-  <div class="d-none d-lg-block td-navbar__search">
+  <div class="d-none d-lg-block">
     {{ 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,57 +1,37 @@
 {{- /*
 
-  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.
+  A modified version of the siderbar-tree.html partial in Docsy, adding:
+  
+  * The "toc.html" partial at L45.
 
 */ -}}
 
-{{ $context := .context -}}
-{{ $sidebarRoot := .sidebarRoot -}}
-{{ $sidebarRootID := .sidebarRootID -}}
-{{ $cacheSidebar := .cacheSidebar -}}
-
-{{ with $context -}}
-{{/* When the sidebar is cached, "active" class is set client side. */ -}}
-{{ $shouldDelayActive := $cacheSidebar -}}
-
+{{/* 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 -}}
 <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" 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 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>
   </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" 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 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>
   </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 .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">
+      {{- 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">
       {{ partial "navbar-lang-selector.html" . }}
     </div>
     {{ end -}}
@@ -65,129 +45,44 @@
     {{ partial "toc.html" . }}
   </nav>
 </div>
-
-{{- end }}{{/* with $context */ -}}
-
 {{ define "section-tree-nav-section" -}}
-  {{/* 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>
+{{ $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) }}
     {{- end }}
-  </li>
-{{- end }}
+    {{- end }}
+  </ul>
+  {{- end }}
+</li>
+{{- end -}}

layouts/_partials/toc.html

@@ -1,29 +1,15 @@
 {{/*
 
-  A copy of the toc.html partial in Docsy, modified to:
+  A modified version of the toc.html partial in Docsy.
 
-  * 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>
+*/}}
+{{ $page := .Params }}
 {{ if not .Params.notoc -}}
-  {{ $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>
+  {{ with .TableOfContents -}}
+    <hr>
+    <div id="toc">
+        <a id="toc-title" href="#">{{ $page.Title }}</a>
+        {{ . }}
     </div>
-    {{ $toc | safeHTML }}
   {{ end -}}
 {{ end -}}
-</div>
-{{/* */ -}}

layouts/docs/baseof.html

@@ -1,14 +1,11 @@
 {{/*
 
-  A copy of the baseof.html partial in Docsy, modified to:
+  A copy of the baseof.html partial in Docsy, modified
+	to remove the right-hand column from the layout.
 
-  * 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" }}
@@ -31,18 +28,20 @@
 <html itemscope itemtype="http://schema.org/WebPage"
     {{- with .Site.Language.LanguageDirection }} dir="{{ . }}" {{- end -}}
     {{ with .Site.Language.Lang }} lang="{{ . }}" {{- end }} {{/**/ -}}
-    class="no-js"
-    {{- $darkMode := partialCached "dark-mode-config.html" "dark-mode-global" -}}
-    {{- if $darkMode.enable }} data-theme-init{{ end }}>
+    class="no-js">
   <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" {{- partialCached "td/scrollspy-attr.txt" . .Section | safeHTMLAttr }}>
+      <div class="td-main">
         <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

@@ -0,0 +1,41 @@
+#!/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)