Migrate to Hugo 0.163.3 + modern hugo-clarity; fix mermaid, search, deprecations

.github/workflows/pages.yml

@@ -43,8 +43,8 @@ jobs:
       (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
     runs-on: ubuntu-22.04
     env:
-      HUGO_VERSION: v0.100.0
-      GO_VERSION: '1.21'
+      HUGO_VERSION: 0.163.3
+      GO_VERSION: '1.26'
       TZ: Europe/Oslo
     steps:
       - name: Checkout
@@ -59,10 +59,11 @@ jobs:
           go-version: ${{ env.GO_VERSION }}
           cache: false
 
-      - name: Install Hugo
-        run: |
-          # CGO is required for extended version
-          CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@${{ env.HUGO_VERSION }}
+      - name: Install Hugo (extended, prebuilt — matches local scoop binary)
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: ${{ env.HUGO_VERSION }}
+          extended: true
 
       - name: Verify Hugo installation
         run: |
@@ -81,7 +82,7 @@ jobs:
           path: |
             blog/resources
             ${{ runner.temp }}/hugo_cache
-          key: hugo-${{ env.HUGO_VERSION }}-${{ runner.os }}-${{ hashFiles('blog/config.*', 'blog/go.sum') }}
+          key: hugo-${{ env.HUGO_VERSION }}-${{ runner.os }}-${{ hashFiles('blog/config/**', 'blog/go.sum') }}
           restore-keys: |
             hugo-${{ env.HUGO_VERSION }}-${{ runner.os }}-
 
@@ -101,7 +102,7 @@ jobs:
           path: |
             blog/resources
             ${{ runner.temp }}/hugo_cache
-          key: hugo-${{ env.HUGO_VERSION }}-${{ runner.os }}-${{ hashFiles('blog/config.*', 'blog/go.sum') }}
+          key: hugo-${{ env.HUGO_VERSION }}-${{ runner.os }}-${{ hashFiles('blog/config/**', 'blog/go.sum') }}
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

.gitignore

@@ -112,5 +112,7 @@ nginx/run/*
 
 .hugo_build.lock
 blog/public
+# Generated Sass/asset cache — always rebuilt by Hugo/CI; committing it caused stale SRI hashes.
+blog/resources/
 
 .tmp/

README.md

@@ -14,9 +14,12 @@ In that case I need to simply run `hugo mod clean`, and then `hugo serve` again.
 
 ### Serve locally
 
+Prerequisites: **Hugo Extended 0.163.3** and **Dart Sass** (kept in sync with CI).
+
 ```sh
+scoop install hugo-extended sass
 cd blog
-go run github.com/gohugoio/hugo@v0.100.0 serve
+make serve   # or: hugo server
 ```
 
 ### Process images

blog/Makefile

@@ -1,6 +1,6 @@
 .PHONY: serve
 
-# Requires Hugo Extended (SCSS compilation). Install: scoop install hugo-extended
-# Pinned in CI to v0.100.0; the local `hugo` should match to avoid theme API drift.
+# Requires Hugo Extended + Dart Sass. Install: scoop install hugo-extended sass
+# Pinned in CI to v0.163.3; the local `hugo` should match to avoid theme API drift.
 serve:
 	hugo server

blog/config/_default/config.toml

@@ -4,7 +4,6 @@ baseURL = 'https://itohi.com/'
 title = "ITOHI — Andrius Mikonis | Embedded Systems, AI & Defence Tech"
 copyright = "2022 @ ITOHI - All rights reserved"
 # canonifyurls = true
-paginate = 13
 theme = ["github.com/chipzoller/hugo-clarity"]
 disqusShortname = "www-itohi-com"
 
@@ -15,6 +14,9 @@ DefaultContentLanguage = "en"
 # [menus]
 # config/_default/menus/menu.xx.toml
 
+[pagination]
+pagerSize = 13
+
 [taxonomies]
 category = "categories"
 tag = "tags"

blog/config/_default/languages.toml

@@ -1,10 +1,10 @@
 
 [en]
   title = "ITOHI — Andrius Mikonis | Embedded Systems, AI & Defence Tech"
-  LanguageName = "English"
+  label = "English"
   weight = 1
 
 [lt]
   title = "ITOHI"
-  LanguageName = "Lietuviškai"
+  label = "Lietuviškai"
   weight = 2

blog/config/_default/markup.toml

@@ -5,6 +5,11 @@
     xhtml = false
   [goldmark.extensions]
     typographer = false
+    [goldmark.extensions.passthrough]
+      enable = true
+      [goldmark.extensions.passthrough.delimiters]
+        block = [['$$', '$$'], ['\[', '\]']]
+        inline = [['$', '$'], ['\(', '\)']]
   [goldmark.parser]
     [goldmark.parser.attribute]
       block = true

blog/config/_default/params.toml

@@ -1,6 +1,11 @@
 # enable search
 enableSearch = true
 
+# Default content language, exposed to the theme's search JS so the English index
+# is fetched from the site root (/index.json) instead of /en/index.json.
+# Must match the top-level DefaultContentLanguage in config.toml.
+defaultContentLanguage = "en"
+
 # additional stylesheets loaded from the static directory (see static/css/)
 customCSS = ["css/custom.css"]
 

blog/go.mod

@@ -2,4 +2,4 @@ module itohi-blog
 
 go 1.19
 
-require github.com/chipzoller/hugo-clarity v0.0.0-20221029154452-0dcfb1a9742c // indirect
+require github.com/chipzoller/hugo-clarity v0.0.0-20260610142153-14929e3c0c03 // indirect

blog/go.sum

@@ -1,2 +1,4 @@
 github.com/chipzoller/hugo-clarity v0.0.0-20221029154452-0dcfb1a9742c h1:RdfM7q3YWnTh4Bf4V/VHCLyLteepauj72lRG9FdWVAk=
 github.com/chipzoller/hugo-clarity v0.0.0-20221029154452-0dcfb1a9742c/go.mod h1:v1JkaKdcLRibyUCalLP2CNeFo6FGzfd4ipEr4dK0+Zg=
+github.com/chipzoller/hugo-clarity v0.0.0-20260610142153-14929e3c0c03 h1:/25VfvPRZnEf3S3tMlt56HzkFgTnrDndqzA9mjb9A/0=
+github.com/chipzoller/hugo-clarity v0.0.0-20260610142153-14929e3c0c03/go.mod h1:v1JkaKdcLRibyUCalLP2CNeFo6FGzfd4ipEr4dK0+Zg=

blog/layouts/_default/_markup/render-codeblock-mermaid.html

@@ -1,2 +1,2 @@
-<div class="mermaid" data-mermaid-content="{{ .Inner | htmlEscape }}"></div>
+<pre class="mermaid">{{ .Inner }}</pre>
 {{ .Page.Store.Set "hasMermaid" true }}

blog/themes/hugo-clarity-master/layouts/_default/rss.xml → blog/layouts/_default/rss.xml

@@ -1,3 +1,5 @@
+{{/* Local override of theme RSS template: .Site.LanguageCode -> .Site.Language.Locale
+     (LanguageCode deprecated in Hugo v0.158.0). Keep in sync with upstream otherwise. */}}
 {{- $pctx := . -}}
 {{- if .IsHome -}}{{ $pctx = .Site }}{{- end -}}
 {{- $pages := slice -}}
@@ -16,10 +18,10 @@
     <title>{{ if eq  .Title  .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}</title>
     <link>{{ .Permalink }}</link>
     <description>Recent content {{ if ne  .Title  .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }}</description>
-    <generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
-    <language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
-    <managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
-    <webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
+    <generator>Hugo -- gohugo.io</generator>{{ with .Site.Language.Locale }}
+    <language>{{.}}</language>{{end}}{{ with .Site.Params.Author.email }}
+    <managingEditor>{{.}}{{ with $.Site.Params.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Params.Author.email }}
+    <webMaster>{{.}}{{ with $.Site.Params.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
     <copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
     <lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
     {{- with .OutputFormats.Get "RSS" -}}
@@ -30,7 +32,7 @@
       <title>{{ .Title }}</title>
       <link>{{ .Permalink }}</link>
       <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
-      {{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
+      {{ with .Site.Params.Author.email }}<author>{{.}}{{ with $.Site.Params.Author.name }} ({{.}}){{end}}</author>{{end}}
       <guid>{{ .Permalink }}</guid>
       <description>
         {{ if ne site.Params.rss_summary false }}

blog/layouts/partials/func/getStylesBundle.html

@@ -0,0 +1,10 @@
+<!-- styles definition -->
+{{/* Local override: source maps disabled so the fingerprinted CSS stays deterministic and
+     its SRI hash matches the served file (a source-map comment appended post-fingerprint was
+     the cause of the dev-server "unstyled page" SRI mismatch). Transpiler is left at the
+     theme default (LibSass); switch to "dartsass" once upstream ships Dart-Sass-clean .sass. */}}
+{{ $options := (dict "targetPath" "css/styles.css" "outputStyle" "compressed" "enableSourceMap" false) }}
+{{ $mainSassFile := "sass/main.sass" }}
+{{ $styles := resources.Get $mainSassFile | resources.ExecuteAsTemplate $mainSassFile . | css.Sass $options | resources.Fingerprint "sha512" }}
+
+{{ return $styles }}

blog/themes/hugo-clarity-master/layouts/partials/header.html → blog/layouts/partials/header.html

@@ -1,3 +1,5 @@
+{{/* Local override of theme partial: .Language.LanguageName -> .Language.Label
+     (LanguageName deprecated in Hugo v0.158.0). Keep in sync with upstream otherwise. */}}
 {{- $params := .Site.Params }}
 {{- $centerLogo := $params.centerLogo }}
 {{ $logo := $params.logo }}
@@ -10,19 +12,19 @@
     {{- end }}
     <div class='nav_body nav_body_{{ default "left" $params.mobileNavigation }}'>
       {{ $context := . }}
-      {{ $menuData := .Site.Data.menu }}
+      {{ $menuData := hugo.Data.menu }}
       {{ with $menuData }}
         {{ partial "nav" (dict "context" $context "menu" $menuData) }}
       {{- else }}
         {{ partial "nav" (dict "context" . "menu" .Site.Menus.main) }}
       {{- end }}
-      {{ if .Site.IsMultiLingual }}
+      {{ if hugo.IsMultilingual }}
       <div class="nav_parent">
         <a href="#" class="nav_item">{{ $params.languageMenuName }}</a>
         <div class="nav_sub">
           <span class="nav_child"></span>
           {{ range .Site.Home.AllTranslations }}
-          <a href="{{ .Permalink }}" class="nav_child nav_item">{{ .Language.LanguageName }}</a>
+          <a href="{{ .Permalink }}" class="nav_child nav_item">{{ .Language.Label }}</a>
           {{ end }}
         </div>
       </div>

blog/layouts/partials/hooks/head-end.html

@@ -1,53 +1,12 @@
 {{- partial "schema.html" . }}
 
 <!-- KaTeX for Math Rendering -->
+{{/* Math delimiters survive Markdown intact via Goldmark passthrough (config markup.toml),
+     so KaTeX renders the raw source directly — no DOM em/strong fixup needed. */}}
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.27/dist/katex.min.css">
 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.27/dist/katex.min.js"></script>
 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.27/dist/contrib/auto-render.min.js"
     onload="
-        // Fix Goldmark's em/strong tag conversion in math blocks before rendering
-        // This is a workaround for Hugo < 0.132 which lacks passthrough extension
-        // IMPORTANT: Protect Mermaid blocks from KaTeX processing
-        // Save Mermaid blocks and replace with placeholders before DOM manipulation
-        const mermaidPlaceholders = new Map();
-        document.querySelectorAll('.mermaid, .mermaid[data-mermaid-content]').forEach((el, idx) => {
-            const placeholderId = 'mermaid-ph-' + idx;
-            const placeholder = document.createElement('div');
-            placeholder.id = placeholderId;
-            placeholder.className = 'mermaid-placeholder';
-            placeholder.style.display = 'none';
-            mermaidPlaceholders.set(placeholderId, el.outerHTML);
-            if (el.parentNode) {
-                el.parentNode.replaceChild(placeholder, el);
-            }
-        });
-
-        // Now do KaTeX processing on the modified DOM (Mermaid blocks are protected)
-        document.body.innerHTML = document.body.innerHTML
-            // Fix display math blocks ($$...$$)
-            .replace(/(\$\$[\s\S]*?\$\$)/g, function(match) {
-                return match.replace(/<\/?em>/g, '_')
-                           .replace(/<\/?strong>/g, '**');
-            })
-            // Fix inline math ($...$) - negative lookbehind/ahead to avoid matching $$
-            // Also skip if preceded by backslash (escaped dollar sign)
-            .replace(/(?<!\\\\)(?<!\$)\$(?!\$)([^\$\n]+?)\$(?!\$)/g, function(match, content) {
-                // Skip if content looks like plain text (no LaTeX commands or special chars)
-                if (!/[\\\\{}^_]/.test(content)) {
-                    return match; // Leave it alone, probably not math
-                }
-                return '$' + content.replace(/<\/?em>/g, '_')
-                                   .replace(/<\/?strong>/g, '**') + '$';
-            });
-
-        // Restore Mermaid blocks
-        mermaidPlaceholders.forEach((html, id) => {
-            const placeholder = document.getElementById(id);
-            if (placeholder && placeholder.parentNode) {
-                placeholder.outerHTML = html;
-            }
-        });
-
         renderMathInElement(document.body, {
             delimiters: [
                 {left: '$$', right: '$$', display: true},
@@ -58,7 +17,6 @@
             throwOnError: false,
             trust: true,
             strict: false,
-            // Ignore text in script, noscript, style, textarea, pre, code, option, and mermaid tags
             ignoredTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code', 'option'],
             ignoredClasses: ['mermaid']
         });

blog/themes/hugo-clarity-master/layouts/partials/i18nlist.html → blog/layouts/partials/i18nlist.html

@@ -1,10 +1,12 @@
+{{/* Local override of theme partial: .Language.LanguageName -> .Language.Label
+     (LanguageName deprecated in Hugo v0.158.0). Keep in sync with upstream otherwise. */}}
 {{ $translationsSize := len .Translations }}
 {{ with .Translations }}
 <div class="post_i18n">
   <h3 class="mb-0">{{ T "translations" }}:</h3>
   <nav class="tags_nav">
     {{ range $index, $_ := . }}
-      <a href="{{ .Permalink }}" class="post_tag button button_translucent">{{ replace (printf "%#v" .Language.LanguageName) "\"" "" }}</a> 
+      <a href="{{ .Permalink }}" class="post_tag button button_translucent">{{ replace (printf "%#v" .Language.Label) "\"" "" }}</a> 
       <!-- {{ if lt $index (sub $translationsSize 1)}} |{{ end }} -->
     {{ end }}
     </nav>