Upgrade docsy to 0.11.0 and hugo to 0.139.0 (#1996)

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

.github/workflows/main.yml

@@ -1,8 +1,7 @@
 name: "Spec"
 
 env:
-  # Cannot build the spec with Hugo 0.125.0 and docsy < 0.10.0 because of https://github.com/google/docsy/issues/1930
+  HUGO_VERSION: 0.139.0
-  HUGO_VERSION: 0.124.1
 
 on:
   push:

README.md

@@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
 
 1. Install the extended version (often the OS default) of Hugo:
    <https://gohugo.io/getting-started/installing>. Note that at least Hugo
-   v0.117.0 is required.
+   v0.123.1 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required

assets/scss/_styles_project.scss

@@ -122,8 +122,11 @@ Custom SCSS for the Matrix spec
 }
 
 /* Customise footer */
-footer {
+.td-footer {
   box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
+  padding-top: 2rem;
+  color: var(--bs-body-color);
+  background-color: var(--bs-body-color-bg);
 }
 
 /* Auto numbering for headings */

changelogs/internal/newsfragments/1996.clarification

@@ -0,0 +1 @@
+Upgrade docsy to 0.11.0 and hugo to 0.138.0.

config.toml

@@ -55,7 +55,6 @@ description = "Home of the Matrix specification for decentralised communication"
 
 [params]
 copyright = "The Matrix.org Foundation CIC"
-privacy_policy = "https://matrix.org/legal/privacy-notice"
 
 [params.version]
 # must be one of "unstable", "current", "historical"
@@ -71,8 +70,6 @@ current_version_url = "https://spec.matrix.org/latest"
 
 # User interface configuration
 [params.ui]
-# Set to true to disable the About link in the site footer
-footer_about_disable = false
 # Collapse HTTP API and event <details> elements
 rendered_data_collapsed = false
 # Hide the search entry in the sidebar
@@ -88,22 +85,28 @@ sidebar_menu_compact = true
 # 	icon = "fa fa-envelope"
 #         desc = "Discussion and help from your fellow users"
 # Developer relevant links. These will show up on right side of footer and in the community page if you have one.
-[[params.links.developer]]
+# [[params.links.developer]]
+# 	name = "GitHub"
+# 	url = "https://github.com/matrix-org"
+# 	icon = "fab fa-github"
+#   desc = "Matrix on GitHub"
+# Custom links shown in the center of the footer. (Only supported by our fork of docsy's 'footer/central' partial.)
+[[params.links.bottom]]
 	name = "GitHub"
 	url = "https://github.com/matrix-org"
 	icon = "fab fa-github"
   desc = "Matrix on GitHub"
-[[params.links.developer]]
+[[params.links.bottom]]
 	name = "GitLab"
 	url = "https://gitlab.matrix.org/matrix-org"
 	icon = "fab fa-gitlab"
   desc = "Matrix on GitLab"
-[[params.links.developer]]
+[[params.links.bottom]]
 	name = "YouTube"
 	url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
 	icon = "fab fa-youtube"
   desc = "Matrix YouTube channel"
-[[params.links.developer]]
+[[params.links.bottom]]
 	name = "Twitter"
 	url = "https://twitter.com/matrixdotorg"
 	icon = "fab fa-twitter"
@@ -130,7 +133,7 @@ sidebar_menu_compact = true
 [module]
   [module.hugoVersion]
     extended = true
-    min = "0.117.0"
+    min = "0.123.1"
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false

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-20241030165433-a14705b7e3ca // indirect
+require github.com/matrix-org/docsy v0.0.0-20241106102557-ec7b98ee4014 // indirect

go.sum

@@ -1,4 +1,4 @@
-github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
+github.com/FortAwesome/Font-Awesome v0.0.0-20240716171331-37eff7fa00de/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
-github.com/matrix-org/docsy v0.0.0-20241030165433-a14705b7e3ca h1:WqKYQIF3JdWxY6b+OZQbdCjczOmELuUxpXhXSXJ/F58=
+github.com/matrix-org/docsy v0.0.0-20241106102557-ec7b98ee4014 h1:CNvxuuURuxkEjA0QN+lRKELc7PRDsX270e8v4GDF3II=
-github.com/matrix-org/docsy v0.0.0-20241030165433-a14705b7e3ca/go.mod h1:TAN2cSMJzy0hnx9OYDbBYluS8raV61UHxT/tfjaLt3g=
+github.com/matrix-org/docsy v0.0.0-20241106102557-ec7b98ee4014/go.mod h1:4Ek1bcdbfU/j8hIatEjNhIs1Yua85FtQf3kLvoYZ0bQ=
-github.com/twbs/bootstrap v5.2.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
+github.com/twbs/bootstrap v5.3.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

layouts/docs/baseof.html

@@ -6,23 +6,26 @@
 */}}
 
 <!doctype html>
-<html lang="{{ .Site.Language.Lang }}" class="no-js">
+<html itemscope itemtype="http://schema.org/WebPage"
+    {{- with .Site.Language.LanguageDirection }} dir="{{ . }}" {{- end -}}
+    {{ with .Site.Language.Lang }} lang="{{ . }}" {{- end }} {{/**/ -}}
+    class="no-js">
   <head>
     {{ partial "head.html" . }}
   </head>
-  <body class="td-{{ .Kind }}">
+  <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="row flex-xl-nowrap">
-          <div class="col-12 col-md-3 col-xl-3 td-sidebar d-print-none">
+          <aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
             {{ partial "sidebar.html" . }}
-          </div>
+          </aside>
-          <main class="col-12 col-md-9 col-xl-7 pl-md-5" role="main">
+          <main class="col-12 col-md-9 col-xl-8 ps-md-5" role="main">
             {{ partial "version-banner.html" . }}
-            {{ partial "breadcrumb.html" . }}
+            {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }}
             {{ block "main" . }}{{ end }}
           </main>
         </div>

layouts/partials/footer.html

@@ -1,39 +0,0 @@
-{{/*
-
-  A modified version of the footer.html partial in Docsy.
-
-*/}}
-
-{{ $links := .Site.Params.links }}
-<footer class="py-5 row d-print-none">
-  <div class="container-fluid mx-sm-5">
-    <div class="row">
-      <div class="col-12 text-center text-xs-center order-sm-3">
-        {{ with $links }}
-        {{ with index . "developer"}}
-        {{ template "footer-links-block"  . }}
-        {{ end }}
-        {{ end }}
-      </div>
-    </div>
-    <div class="row">
-      <div class="col-12 text-center py-2 order-sm-3">
-        {{ with .Site.Params.copyright }}<small>&copy; {{ now.Year}} {{ .}}</small>{{ end }}
-	{{ if not .Site.Params.ui.footer_about_disable }}
-		{{ with .Site.GetPage "about" }}<p class="mt-2"><a href="{{ .RelPermalink }}">{{ .Title }}</a></p>{{ end }}
-	{{ end }}
-      </div>
-    </div>
-  </div>
-</footer>
-{{ define "footer-links-block" }}
-<ul class="list-inline mb-0">
-  {{ range . }}
-  <li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="{{ .name }}" aria-label="{{ .name }}">
-    <a class="text-dark" target="_blank" rel="noopener noreferrer" href="{{ .url }}">
-      <i class="{{ .icon }}"></i>
-    </a>
-  </li>
-  {{ end }}
-</ul>
-{{ end }}

layouts/partials/footer/center.html

@@ -0,0 +1,30 @@
+{{- /*
+
+    Modified version of the footer/center.html partial of Docsy, adding "bottom"
+    links on top of the copyright.
+
+*/ -}}
+
+{{ with .Site.Params.links -}}
+  {{ with index . "bottom" -}}
+    {{- partial "footer/links.html"  . -}}
+  {{ end -}}
+{{ end -}}
+
+<div class="mt-2 mb-3">
+{{ partial "footer/copyright.html"  . -}}
+</div>
+
+{{ with .Site.Params.privacy_policy -}}
+  <span class="ms-2"><a href="{{ . }}" target="_blank" rel="noopener">{{ T "footer_privacy_policy" }}</a></span>
+{{- end -}}
+
+{{ if ne .Site.Params.ui.footer_about_disable nil -}}
+  {{ warnf "Config parameter '.params.ui.footer_about_disable' is DEPRECATED, use '.params.ui.footer_about_enable' instead." -}}
+{{ end -}}
+
+{{ if or .Site.Params.ui.footer_about_enable (eq .Site.Params.ui.footer_about_disable false) -}}
+  {{ with .Site.GetPage "about" -}}
+    <p class="td-footer__about mt-2"><a href="{{ .RelPermalink }}">{{ .Title }}</a></p>
+  {{- end -}}
+{{ end -}}

layouts/partials/navbar.html

@@ -1,10 +1,10 @@
-{{/*
+{{- /*
 
   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.
 
-*/}}
+*/ -}}
 
 {{ $cover := and
     (.HasShortcode "blocks/cover")
@@ -12,8 +12,8 @@
 -}}
 {{ $baseURL := urls.Parse $.Site.Params.Baseurl -}}
 
-<nav class="td-navbar navbar-light js-navbar-scroll
+<nav class="td-navbar js-navbar-scroll
-            {{- if $cover }} td-navbar-cover {{- end }}">
+            {{- 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 }}">
     {{- /**/ -}}
@@ -26,10 +26,11 @@
     </span>
     {{- /**/ -}}
     <span class="navbar-brand__name">
-		specification
+      specification
     </span>
     {{- /**/ -}}
-	<span class="navbar-version"> &mdash; {{ partial "version-string" . }}</span>
+	  <span class="navbar-version"> &mdash; {{ partial "version-string" . }}</span>
+    {{- /**/ -}}
   </a>
   <div class="td-navbar-nav-scroll ms-md-auto" id="main_navbar">
     <ul class="navbar-nav">
@@ -66,6 +67,11 @@
         {{ partial "navbar-lang-selector.html" . -}}
       </li>
       {{ end -}}
+      {{ if .Site.Params.ui.showLightDarkModeMenu -}}
+      <li class="td-light-dark-menu nav-item dropdown">
+        {{ partial "theme-toggler" . }}
+      </li>
+      {{ end -}}
     </ul>
   </div>
   <div class="d-none d-lg-block">

layouts/partials/sidebar-tree.html

@@ -1,10 +1,10 @@
-{{/*
+{{- /*
 
   A modified version of the siderbar-tree.html partial in Docsy, adding:
   
   * The "toc.html" partial at L45.
 
-*/}}
+*/ -}}
 
 {{/* We cache this partial for bigger sites and set the active class client side. */ -}}
 {{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}}
@@ -38,7 +38,7 @@
     {{ $navRoot := cond (and (ne .Params.toc_root true) (eq .Site.Home.Type "docs")) .Site.Home .FirstSection -}}
     {{ $ulNr := 0 -}}
     {{ $ulShow := .Site.Params.ui.ul_show | default 1 -}}
-    {{ $sidebarMenuTruncate := .Site.Params.ui.sidebar_menu_truncate | default 50 -}}
+    {{ $sidebarMenuTruncate := .Site.Params.ui.sidebar_menu_truncate | default 100 -}}
     <ul class="td-sidebar-nav__section pe-md-3 ul-{{ $ulNr }}">
       {{ template "section-tree-nav-section" (dict "page" . "section" $navRoot "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" (add $ulShow 1)) }}
     </ul>
@@ -59,6 +59,11 @@
 {{ $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 -}}
@@ -80,4 +85,4 @@
   </ul>
   {{- end }}
 </li>
-{{- end }}
+{{- end -}}