diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ef8353cc..92b841f4 100644 --- a/.github/workflows/main.yml +++ b/.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: diff --git a/assets/js/toc.js b/assets/js/toc.js index 89a83ced..a7103f9d 100644 --- a/assets/js/toc.js +++ b/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; diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index f20dc096..cd9937a9 100644 --- a/assets/scss/_styles_project.scss +++ b/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; diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss index c2ec03c6..75e5379f 100644 --- a/assets/scss/_variables_project.scss +++ b/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; diff --git a/changelogs/internal/newsfragments/2287.clarification b/changelogs/internal/newsfragments/2287.clarification new file mode 100644 index 00000000..5d0bdcc5 --- /dev/null +++ b/changelogs/internal/newsfragments/2287.clarification @@ -0,0 +1 @@ +Upgrade to docsy v0.13.0. diff --git a/config/_default/hugo.toml b/config/_default/hugo.toml index 2fb69279..76c3f9bb 100644 --- a/config/_default/hugo.toml +++ b/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'] diff --git a/go.mod b/go.mod index 60143ea9..6b13c46b 100644 --- a/go.mod +++ b/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 diff --git a/go.sum b/go.sum index ea991476..3897374a 100644 --- a/go.sum +++ b/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= diff --git a/layouts/_markup/render-passthrough.html b/layouts/_markup/render-passthrough.html index 425471a9..d5f85ded 100644 --- a/layouts/_markup/render-passthrough.html +++ b/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" . }} diff --git a/layouts/_partials/breadcrumb.html b/layouts/_partials/breadcrumb.html index af3a9551..bfe89399 100644 --- a/layouts/_partials/breadcrumb.html +++ b/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 -}} -{{ end }} +
    + {{- template "breadcrumbnav" (dict "p1" . "p2" .) }} +
+ +{{ 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 }} -
  • - {{ .p1.LinkTitle }} -
    • -{{ 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 }} +
  • + {{ if $isActive -}} + {{ .p1.LinkTitle -}} + {{ else -}} + {{ .p1.LinkTitle }} + {{- end -}} +
    • +{{- end -}} diff --git a/layouts/_partials/navbar.html b/layouts/_partials/navbar.html index 0de6f46c..0a563d8f 100644 --- a/layouts/_partials/navbar.html +++ b/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 -}} -{{ 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 -}} diff --git a/layouts/_partials/sidebar-tree.html b/layouts/_partials/sidebar-tree.html index dba63f3a..e5f00807 100644 --- a/layouts/_partials/sidebar-tree.html +++ b/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: + + * 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 -}} +
    {{ if not .Site.Params.ui.sidebar_search_disable -}} +
    {{ partial "search-input.html" . }} -
    - {{ else -}} + + {{- else -}} +
    {{ partial "search-input.html" . }} -
    - {{ end -}} + + {{- end }} + {{/* */ -}} +
    + +{{- 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 -}} -
  • - {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}} - - - {{ else -}} - {{ with $s.Params.Icon}}{{ end }}{{ $s.LinkTitle }} - {{- end }} - {{- if $withChild }} - {{- $ulNr := add $ulNr 1 }} - - {{- end }} -
    • -{{- end -}} + +{{- end }} diff --git a/layouts/_partials/toc.html b/layouts/_partials/toc.html index 318335f2..adfbd161 100644 --- a/layouts/_partials/toc.html +++ b/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 +*/ -}} + +
    {{ if not .Params.notoc -}} - {{ with .TableOfContents -}} -
    -
    - {{ $page.Title }} - {{ . }} + {{ $toc := .TableOfContents -}} + {{ if and $toc (ne $toc ``) -}} +
    + {{ .Params.Title }} +
    + {{ $toc | safeHTML }} {{ end -}} {{ end -}} +
    +{{/* */ -}} diff --git a/layouts/docs/baseof.html b/layouts/docs/baseof.html index b5b7a0f0..e18864dd 100644 --- a/layouts/docs/baseof.html +++ b/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 @@ + class="no-js" + {{- $darkMode := partialCached "dark-mode-config.html" "dark-mode-global" -}} + {{- if $darkMode.enable }} data-theme-init{{ end }}> {{ partial "head.html" . }} - {{ if .Page.Store.Get "hasMath" }} - - - {{ end }}
    {{ partial "navbar.html" . }}
    -
    +