Update docsy to v0.8.0 (#1699)

Signed-off-by: Kévin Commaille <[email protected]>
matrix-org · Feb 27, 2024 · b136b35 · b136b35
1 parent e2dc5a3
commit b136b35
Show file tree

Hide file tree

Showing 14 changed files with 381 additions and 359 deletions.
diff --git a/.gitmodules b/.gitmodules
diff --git a/README.md b/README.md
@@ -61,13 +61,12 @@ 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.93.0 is required.
+   v0.110.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required
    to process the SCSS.)
-2. Run `npm i` to install the dependencies and fetch the docsy git submodule.
-   Note that this will require NodeJS to be installed.
+2. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
 3. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
    page and is not required.
 4. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313

diff --git a/assets/scss/custom.scss → assets/scss/_styles_project.scss b/assets/scss/custom.scss → assets/scss/_styles_project.scss
@@ -18,9 +18,6 @@ limitations under the License.
 Custom SCSS for the Matrix spec
 */
 
-@import "variables_project";
-@import "variables";
-
 /* Import the CSS classes for the syntax highlighter.
  *
  * This is generated with:
@@ -49,6 +46,10 @@ Custom SCSS for the Matrix spec
 
   }
 
+  .nav-link {
+    font-weight: normal;
+  }
+
   a {
     color: $black;
   }
@@ -292,7 +293,7 @@ footer {
 }
 
 /* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
-.rendered-data {
+.td-content .rendered-data {
   background-color: $secondary-lightest-background;
   padding: 0.85rem;
   margin: 0.85rem 0;
@@ -346,7 +347,7 @@ footer {
   }
 
   p code, table code {
-    background-color: inherit;
+    background-color: transparent;
   }
 
   table {
@@ -396,6 +397,7 @@ footer {
 
     th, td, caption {
       padding: 1rem;
+      border-top: 1px $table-border-color solid;
     }
 
     &.object-table, &.response-table, &.content-type-table {
@@ -408,14 +410,12 @@ footer {
 
             // ... but avoid double border between caption and table
             border-bottom: 0;
-        }
 
-        caption, tbody tr {
-            background-color: $table-row-default;
+            background-color: $secondary-lighter-background;
         }
 
-        tbody tr:nth-child(even) {
-            background-color: $table-row-alternate;
+        tbody tr {
+            --bs-table-striped-bg: #{$secondary-lighter-background};
         }
     }
 
@@ -517,3 +517,15 @@ dd {
     border-radius: 0.25rem;  // was $border-radius, but that var isn't accessible here.
   }
 }
+
+/* Style for breadcrumbs */
+.td-breadcrumbs {
+  padding: .75rem 1rem;
+  background-color: #eee;
+  border-radius: .25rem;
+  margin-bottom: 1rem;
+
+  .breadcrumb {
+    margin: 0;
+  }
+}
diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss
@@ -20,7 +20,7 @@ $dark: #333;
 $gray-100: #FBFBFB;
 
 $secondary-background: #E5F5FB;
-$secondary-lighter-background: #F4FaFC;
+$secondary-lighter-background: #F4FAFC;
 $secondary-lightest-background: #FBFDFD;
 
 
@@ -33,8 +33,7 @@ $warning-background: #FFE0E0;
 // colours for definition tables.
 // the border colour matches that used for "highlight" divs
 $table-border-color: rgba(black, .125);
-$table-row-alternate: $secondary-lightest-background;
-$table-row-default: $secondary-lighter-background;
+$table-bg: $secondary-lightest-background;
 
 /* Configure docsy to use the default system fonts instead of Google Fonts.
  * See https://www.docsy.dev/docs/adding-content/lookandfeel/#fonts */

diff --git a/changelogs/internal/newsfragments/1699.clarification b/changelogs/internal/newsfragments/1699.clarification
@@ -0,0 +1 @@
+Update Docsy to v0.8.0.
diff --git a/config.toml b/config.toml
@@ -7,9 +7,6 @@ canonifyURLs = true
 
 enableRobotsTXT = true
 
-# Hugo allows theme composition (and inheritance). The precedence is from left to right.
-theme = ["docsy"]
-
 # We disable RSS, because (a) it's useless, (b) Hugo seems to generate broken
 # links to it when used with a --baseURL (for example, https://spec.matrix.org/v1.4/
 # contains `<link rel="alternate" type="application/rss&#43;xml" href="/v1.4/v1.4/index.xml">`).
@@ -23,6 +20,21 @@ languageName ="English"
 # Weight used for sorting.
 weight = 1
 
+# Entries in the main menu in the header.
+[menus]
+[[menus.main]]
+    name = 'Foundation'
+    url = 'https://matrix.org/foundation/'
+    weight = 10
+[[menus.main]]
+    name = 'FAQs'
+    url = 'https://matrix.org/faq'
+    weight = 20
+[[menus.main]]
+    name = 'Blog'
+    url = 'https://matrix.org/blog/posts'
+    weight = 30
+
 [markup]
   [markup.goldmark]
     [markup.goldmark.renderer]
@@ -111,3 +123,13 @@ sidebar_menu_compact = true
     X-Frame-Options = "sameorigin"
     Access-Control-Allow-Origin = "*"
     Access-Control-Allow-Methods = "GET"
+
+# hugo module configuration
+
+[module]
+  [module.hugoVersion]
+    extended = true
+    min = "0.110.0"
+  [[module.imports]]
+    path = "github.com/matrix-org/docsy"
+    disable = false
diff --git a/go.mod b/go.mod
@@ -0,0 +1,5 @@
+module github.com/matrix-org/matrix-spec
+
+go 1.12
+
+require github.com/matrix-org/docsy v0.0.0-20231227121313-d55dbaf3aaaf // indirect
diff --git a/go.sum b/go.sum
@@ -0,0 +1,4 @@
+github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
+github.com/matrix-org/docsy v0.0.0-20231227121313-d55dbaf3aaaf h1:e1mutHvMYJ92F/VkAp2ixQthXf6zNHJll4wYGbBHznI=
+github.com/matrix-org/docsy v0.0.0-20231227121313-d55dbaf3aaaf/go.mod h1:TAN2cSMJzy0hnx9OYDbBYluS8raV61UHxT/tfjaLt3g=
+github.com/twbs/bootstrap v5.2.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
diff --git a/layouts/partials/breadcrumb.html b/layouts/partials/breadcrumb.html
@@ -8,8 +8,8 @@
 */}}
 
 {{ if not .IsHome }}
-<nav aria-label="breadcrumb" class="d-none d-md-block d-print-none">
-	<ol class="breadcrumb spb-1">
+<nav aria-label="breadcrumb" class="td-breadcrumbs">
+	<ol class="breadcrumb">
 {{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
 	</ol>
 </nav	>

diff --git a/layouts/partials/hooks/head-end.html b/layouts/partials/hooks/head-end.html
@@ -15,14 +15,3 @@
 */}}
 <link rel="preload" href="{{ "/css/fonts/Inter.css" | relURL }}" as="style">
 <link rel="stylesheet" href="{{ "/css/fonts/Inter.css" | relURL }}">
-
-{{ $scss := "scss/custom.scss"}}
-{{ if .Site.IsServer }}
-{{/* Note the missing postCSS. This makes it snappier to develop in Chrome, but makes it look sub-optimal in other browsers. */}}
-{{ $css := resources.Get $scss | toCSS (dict "enableSourceMap" true) }}
-<link href="{{ $css.RelPermalink }}" rel="stylesheet">
-{{ else }}
-{{ $css := resources.Get $scss | toCSS (dict "enableSourceMap" false) | postCSS | minify | fingerprint }}
-<link rel="preload" href="{{ $css.RelPermalink }}" as="style">
-<link href="{{ $css.RelPermalink }}" rel="stylesheet" integrity="{{ $css.Data.integrity }}">
-{{ end }}
diff --git a/layouts/partials/navbar.html b/layouts/partials/navbar.html
@@ -6,39 +6,74 @@
 
 */}}
 
-{{ $cover := .HasShortcode "blocks/cover" }}
-<nav class="js-navbar-scroll navbar navbar-expand navbar-light {{ if $cover}} td-navbar-cover {{ end }}flex-column flex-md-row td-navbar">
-        <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}">
-		<span class="navbar-logo">{{ with resources.Get "icons/logo.svg" }}{{ ( . | minify).Content | safeHTML }}{{ end }}</span><span class="font-weight-bold">specification</span><span class="navbar-version"> &mdash; {{ partial "version-string" . }}</span>
-	</a>
-	<div class="td-navbar-nav-scroll ml-md-auto" id="main_navbar">
-		<ul class="navbar-nav mt-2 mt-lg-0">
+{{ $cover := and
+    (.HasShortcode "blocks/cover")
+    (not .Site.Params.ui.navbar_translucent_over_cover_disable)
+-}}
+{{ $baseURL := urls.Parse $.Site.Params.Baseurl -}}
 
-			<li class="nav-item mr-4 mb-2 mb-lg-0"><a href="https://matrix.org/foundation/">Foundation</a>
-			</li>
-
-      <li class="nav-item mr-4 mb-2 mb-lg-0"><a href="https://matrix.org/faq/">FAQs</a>
-			</li>
-
-      <li class="nav-item mr-4 mb-2 mb-lg-0"><a href="https://matrix.org/blog/posts">Blog</a>
+<nav class="td-navbar navbar-light js-navbar-scroll
+            {{- if $cover }} td-navbar-cover {{- end }}">
+<div class="container-fluid flex-column flex-md-row">
+  <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}">
+    {{- /**/ -}}
+    <span class="navbar-brand__logo navbar-logo">
+      {{- if ne .Site.Params.ui.navbar_logo false -}}
+        {{ with resources.Get "icons/logo.svg" -}}
+          {{ ( . | minify).Content | safeHTML -}}
+        {{ end -}}
+      {{ end -}}
+    </span>
+    {{- /**/ -}}
+    <span class="navbar-brand__name">
+		specification
+    </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">
+      {{ $p := . -}}
+      {{ range .Site.Menus.main -}}
+      <li class="nav-item">
+        {{ $active := or ($p.IsMenuCurrent "main" .) ($p.HasMenuCurrent "main" .) -}}
+        {{ $href := "" -}}
+        {{ with .Page -}}
+          {{ $active = or $active ( $.IsDescendant .) -}}
+          {{ $href = .RelPermalink -}}
+        {{ else -}}
+          {{ $href = .URL | relLangURL -}}
+        {{ end -}}
+        {{ $isExternal := ne $baseURL.Host (urls.Parse .URL).Host -}}
+        <a {{/**/ -}}
+          class="nav-link {{- if $active }} active {{- end }}" {{/**/ -}}
+          href="{{ $href }}"
+          {{- if $isExternal }} target="_blank" rel="noopener" {{- end -}}
+        >
+            {{- .Pre -}}
+            <span>{{ .Name }}</span>
+            {{- .Post -}}
+        </a>
       </li>
-
-			{{ if  .Site.Params.versions }}
-			<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 dropdown d-none d-lg-block">
-				{{ partial "navbar-lang-selector.html" . }}
-			</li>
-			{{ end }}
-		</ul>
-	</div>
-	<div class="navbar-nav d-none d-lg-block">{{ partial "search-input.html" . }}</div>
+      {{ end -}}
+      {{ if .Site.Params.versions -}}
+      <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 dropdown d-none d-lg-block">
+        {{ partial "navbar-lang-selector.html" . -}}
+      </li>
+      {{ end -}}
+    </ul>
+  </div>
+  <div class="d-none d-lg-block">
+    {{ partial "search-input.html" . }}
+  </div>
+</div>
 </nav>
 
-
 {{ define "partials/version-string" }}
     {{ $ret := "unstable version"}}