Hugo on Schallberts Blog

Hugo vs. Jekyll: Benchmark

Schallbert — Wed, 30 Sep 2026

Ladezeiten

Schauen wir uns mal an, wie meine Seite mit Jekyll gegenüber Hugo lädt. Hierfür öffne ich die Entwickleroptionen (F12) in meinem Browser, wähle das Network-Tab an und klicke dort auf All. Anschließend lade ich die Seite neu.

Dabei entsteht die folgende Auflistung:

Im Bild unten: Ladezeit meiner Landing Page mit Hugo

Zu erwähnen ist, dass ich hier eigentlich gar nicht Jekyll mit Hugo vergleiche, sondern lediglich deren Ausgabe und daher die gewählten Themes maßgeblich für Größe und Ladezeit verantwortlich sind. Also vergleiche ich praktisch das minimalmistakes theme in Jekyll mit dem terminal theme in Hugo. Hugo ist in diesem Falle etwa 10% schneller als Jekyll.

Im Bild unten: Ladezeit meiner Landing Page mit Jekyll

Größe

Ein anderes Diagramm erhalte ich, wenn ich ganz unten links auf die Stoppuhr klicke und damit eine performance analysis ausführe. Die Kuchendiagramme zeigen für meine Implementierung in Jekyll den größten Anteil in Bildern, gefolgt von CSS und JS. In Hugo geht JS gegen null, und auch der Anteil von CSS ist geschrumpft.

Die folgende Tabelle zeigt ein paar meiner Seiten im direkten Vergleich. Allerdings ist die Übersicht mit Vorsicht zu genießen: Die Werte ändern sich schon mal, wenn ich neu lade (auch mit ausgeschaltetem Cache). Gerade bei eingebundenen Inhalten Dritter wie meinen Videos kommen hier teils stark unterschiedliche Werte heraus. Insgesamt habe ich mit Hugo und Terminal deutliche Optimierungen vorliegen.

Item	minimal-mistakes	terminal-schallbert		Jekyll	Hugo
	transferred	[kB]	Diff [%]	time	[ms]	Diff [%]
Landing	163.47	98.68	-39	30	30	0
Post	2861	1767	-38	340	270	-20
List page	1507	140	-90	30	30	0

Manuell implementiert in Hugo hatte ich das bedingte Laden von Katex nur auf Seiten, wo mathematische Ausdrücke auftauchen (das spart oftmals 90kB min.css).
Mit Hugo habe ich kleinere CSS-Dateien. Es wird nur geladen, was ich auch wirklich verwende. Es gibt kaum noch Code, der nicht angefahren wird.
Automatisch in Hugo sind Medien-Vorschaudateien von den hochauflösenden Dateien abgeleitet und per Bildprozessor auf die Darstellungsverhältnisse im gebauten Zustand platzoptimiert. Diese Optimierung spart bei vielen, klein dargestellten Bildern eine Menge Bandbreite.
Das Terminal-Theme zeigt anders als minimalmistakes keine Kärtchen für “weitere Posts” an. Dies spart die Übertragung von vier Vorschaubildern.
In Hugo habe ich fast gar keine Javascript-Inhalte mehr - eines der Ziele, das ich mir gesteckt hatte.

Auslieferung/Continuous Deployment

Für Jekyll gestaltete sich Bauen und Ausliefern in Gitea etwas hakelig: erst mit einem Jekyll-Dockerimage war ich in der Lage, ruby richtig aufzusetzen. Damit und weil ich meinen Actions nicht erlaube zu cachen dauert das Bauen ziemlich lang: Erst den aktuellen Docker-Container ziehen, ruby und jekyll updaten, gems installieren, die Quelldateien auschecken, anschließend bauen und ausliefern - hier vergehen selbst unter optimalen Bedingungen mehr als 90 Sekunden, bis ein neuer Artikel live ist.

Für Hugo geht der ganze Prozess dank schnellerer Bauzeiten und vorgefertigter Container (siehe dazu mein Artikel zum Thema Continuous Deployment Pipeline mit Hugo in Docker) viel schneller vonstatten.

Selbst im ungünstigsten Fall (siehe Build unten), z.B. nach einem Neustart des Runners nach Update und einer Änderung im Docker-Repository für meinen Hugo Container, bleibe ich weit unter 30 Sekunden.

Komplexität

Ganz klar: Hugo ist hier im Vergleich zu Jekyll unschlagbar.

Da Themes in Hugo steckbare Module sind, benötigen sie keinen Abhängigkeitsbaum in Form von Gems wie bei Jekyll zum Nachladen und installieren. Entsprechend kann hier viel weniger kaputt gehen. Für mich lokal verringert sich die Bauzeit für einen “full build” (zweisprachig) um 75% und auch das automatische Bauen bei Veränderung meiner Markdown-Dateien ist sowohl 5x schneller als auch aussagekräftiger: Wenn ich in Jekyll nämlich “incremental build” einschalte, dann gibt es keine aktualisieren Paginator-Seiten mehr - sprich Listenansichten und Übersichtsseiten werden nicht mit gebaut.

Auf der anderen Seite kann ich in Jekyll sehr flexibel und feingranular selbst eingreifen, eigene Gems entwerfen und recht einfach besondere Gimmicks für meine Seite herstellen wie ein mitscrollendes Inhaltsverzeichnis. Jenes vermisse ich in Hugo etwas.

Fazit: Für die tagtägliche Benutzbarkeit gefällt mir Hugo ganz klar besser als Jekyll. - schallbert, Sep-2026

Continuous Deployment für Hugo

Schallbert — Tue, 15 Sep 2026

Gerade habe ich meine Website von Hugo auf Jekyll umgezogen. Nun will ich sie automatisiert bauen und Änderungen ausrollen, sobald ich einen Artikel fertiggestellt und ihn per git push und anschließendem Merge in main auf meine Gitea-Instanz geschoben habe.

Die Befehlskette

Ich habe einen VPS gemietet, auf dem ich alle Anwendungen in Docker laufen lasse. Die Aufgabe ist nun, einen workflow in Gitea zu bauen (“Actions”), welcher das Update im Repository auscheckt, es hugo zur Verfügung stellt, dort die HTML-Seiten erzeugen lässt, und sie anschließend so auf der Festplatte ablegt, dass mein Webserver die Dateien einlesen und ausliefern kann.

Erfahrungswerte

Das alles hatte ich für meine Website in Jekyll bauen und ausrollen können, daher kann ich auf ein paar Erfahrungswerte zurückgreifen.

Üblicherweise nutzt man dafür standardisierte Aktionen. Ich vereinfache mal stark und liste nur die Hauptdarsteller auf, ohne in fiese Details wie Rechtevergabe (darf Hugo in diesen Ordner schreiben? Hat der hugo-user genügend Rechte?) tiefer einzugehen:

checkout stellt einen gewünschten Stand des Quellrepository bereit
actions-hugo installiert hugo in der virtuellen Maschine der Action, sodass die Website gebaut werden kann
upload-artifact lädt die von hugo erstellte Seite auf den Webserver hoch

Da ich jedoch auf ein- und derselben Maschine in Docker unterwegs bin, kann ich mir das aufwendige Einwählen auf dem Webserver “von außen” sparen. Daher gehe ich einen anderen Weg.

Docker shared Volumes

Ich kann meiner Caddy-Anwendung direkt die gebauten Dateien zur Verfügung stellen, wenn ich das von ihr gelesene Volume bis in die Action weiterreiche.

Aufgepasst: Action volume != Hugo volume

Doch das funktioniert mit actions-hugo nicht: Sie ist selbst kein Docker container, kann also keine Volumes einbinden. Sie baut zwar die Webseite fertig; sobald die Aktion jedoch durchgelaufen ist, reißt sie die Artefakte mit ins Nirvana.

Ich benötige also eine hugo-Runtime, die selbst in einem Docker-Container läuft - ganz nach dem DinD-Ansatz. Diesem kann ich dann das von Caddy verwendete Volume mit Schreibzugriff durchreichen.

Der Workflow

Doch welchen Docker-Container soll ich nehmen?

Man stelle sich nun mehrere Stunden der Recherche und viele Fehlversuche beim Einrichten des Workflows auf meinem Server vor.

Folgendes ergab sich aus meinen Untersuchungen:

checkout@v4 benötigt node.js, und zwar mindestens Version node:18. Der Docker-Container (und das darunterliegende Betriebssystem des Runners!) müssen es installiert haben bzw. unterstützen.
Die Action benötigt git. Auch dies muss der Docker-container idealerweise bereits mitbringen.
Hugo braucht go. Klingt soweit logisch.

Runner-Betriebssystem anpassen

Mein Runner aus dem Jahr 2023 ist inzwischen in die Tage gekommen. Er basiert auf node:16-bullseye, eine Debian-basierte VM. Ich probiere etwas mit Alpine herum, doch diese Installation ist zu minimal für meine Zwecke und lässt mich mit vielen manuellen Anpassungen zurück. Schließlich muss der Runner noch andere Workflows ausführen als diesen hier. Ich entscheide mich letztendlich, bei Debian zu bleiben und nur die Node-Version hochzuziehen. Die Umsetzung in der Runner-Konfiguration sieht dann wie folgt aus:

# /gitea/runner/config.yml

 # The labels of a runner are used to determine which jobs the runner can run, and how to run them.
 # Like: ["macos-arm64:host", "ubuntu-latest:docker://node:16-bullseye", "ubuntu-22.04:docker://node:16-bullseye"]
 # If it's empty when registering, it will ask for inputting labels.
 # If it's empty when execute `deamon`, will use labels in `.runner` file.
 labels: [ubuntu-latest:docker://node:20-bullseye]

Anschließend muss der Runner-Container neu gestartet werden. Idealerweise bootet man Gitea gleich mit durch, dann funktioniert das Registrieren des Runners auch zuverlässig.

Das Workflow-Script schreiben

Um die oben beschriebenen Abhängigkeiten abzudecken entscheide ich mich für einen “batteries included”-Ansatz. So kann ich die Bausteine einfach ohne manuelle Anpassungen zusammenstecken und vertraue auf langfristige Wartung und Pflege der Container, da sie wirklich sehr häufig verwendet werden (Größenordnung mehrere Millionen Pulls). Diese Webseite half mir sehr bei der Auswahl.

Schließlich erstelle ich meinen Workflow basierend auf dem Container von Hugomods.

# /.gitea/workflows/build-deploy-with-hugo.yml

name: Deploy Hugo site
run-name: ${{ gitea.actor }} builds Hugo site
on:
 push:
 branches:
 - main

jobs:
 # Build job
 build:
 runs-on: ubuntu-latest # this is the "label" the runner will use and map to docker target OS
 container: 
 image: hugomods/hugo:latest
 volumes: 
 - /tmp/blog-artifacts:/tmp/blog-artifacts

 steps:
 - name: --- CHECKOUT ---
 uses: actions/checkout@v4
 with:
 submodules: recursive  # Fetches Hugo themes
 fetch-depth: 0

 - name: --- BUILD WITH HUGO --- # chown -R hugo /tmp/blog-artifacts
 run: |
 hugo \
 --minify \
 --cleanDestinationDir \
 --destination /tmp/blog-artifacts

Zielordner bereinigen

Ich habe mich im obigen Beispiel für ein “direktes Deployment” entschieden, ohne Netz und doppelten Boden, und ohne, dass ich die Artefakte herumkopiere oder gar den Server neu starte. Begründung: Der Hugo-Bauprozess benötigt für Meine Seite weniger als 2000ms. Nur in diesem Fenster kann Caddy theoretisch eine “korrupte” Datenbank sehen und ausliefern, also nur während die Platte vom Hugo-Build-Workflow noch beschrieben wird.

Um Inkonsistenzen trotzdem weitgehend zu vermeiden, gebe ich Hugo die Option --cleanDestinationDir mit. Damit ist das Zielverzeichnis stets sauber und Caddy wird im Zweifel keine defekte Seite anzeigen, sondern höchstens eine 404-Fehlermeldung erzeugen.

Submodules

Wie in meiner Projektdokumentation geschrieben, kann man in Hugo zum Laden von Themes sogenannte submodules verwenden. Diese werden in das Projekt eingeklickt und können, wenn korrekt verlinkt, dann auch im Workflow verwendet werden:

 with:
 submodules: recursive  # Fetches Hugo themes
 fetch-depth: 0

Ist alles richtig eingestellt, sollte es nicht zu folgender Fehlermeldung kommen:

# workflow action's error message due to incoherent submodules' commit references
# actions/checkout@v4:
Fetching submodules
/usr/bin/git submodule sync
/usr/bin/git -c protocol.version=2 submodule update --init --force
Submodule 'themes/terminal' (https://github.com/panr/hugo-theme-terminal.git) registered for path 'themes/terminal'
Cloning into '/workspace/schallbert/blog-hugo/themes/terminal'...
fatal: remote error: upload-pack: not our ref 719505fc89332baa69bffb90cee708ff124dd143
Fetched in submodule path 'themes/terminal', but it did not contain 719505fc89332baa69bffb90cee708ff124dd143. Direct fetching of that commit failed.
Error: The process '/usr/bin/git' failed with exit code 1
Error: Process completed with exit code 1.

Voraussetzung ist, dass man die Submodule auch lokal richtig geladen hat:

schallbert@machine:~ git submodule add -f https://github.com/<my/hugo-theme>.git themes/my-hugo-theme
schallbert@machine:~ git submodule update --init --recursive

Die Statusabfrage darf keinen leeren String zurückgeben, sondern muss einen Commit hash beinhalten. Beispiel:

schallbert@machine:~ git submodule status 
44d9a1890d228745ffc300b37a7d73e940ef9fa9 themes/terminal (v4.2.5)

Weiteres Zeugnis ist die .gitmodules-Datei, welche eine Referenz auf das Theme beinhalten muss:

schallbert@machine:➜/blog git:(main) ✗ nano .gitmodules
 [submodule "themes/terminal"]
 path = themes/terminal
 url = https://github.com/panr/hugo-theme-terminal.git

Funktioniert das nicht, so sind die Submodule nochmal komplett zu entfernen und antschließend wie oben beschrieben neu zu initialisieren:

git submodule deinit -f themes/<my-theme>
git rm -r --cached themes/<my-theme>
rm -rf .git/modules/themes/<my-theme>

Typische Probleme: Hugo-Versionen und Deprecations

Nun verlief die checkout-Aktion erfolgreich. Doch der Build mit Hugo schlägt fehl:

 error calling partial: "/workspace/schallbert/blog-hugo/layouts/_partials/head.html:37:40": execute of template failed: template: _partials/head.html:37:40: executing "_partials/head.html" at <$.Page.Language.Locale>: can't evaluate field Locale in type *langs.Language
Error: Process completed with exit code 1.

Lokal auf meiner Maschine baut Hugo erfolgreich, gibt aber ein paar Warnungen heraus:

Änderungen der Language-identifier und -Auswertung ab v0.158

schallbert@machine:➜/blog git:(main) ✗ hugo build --logLevel info 
WARN deprecated: site.Language.Locale was deprecated in Hugo v0.158.0 and will be removed in a future release. Use .Page.Language.Locale instead.
WARN deprecated: .Language.Lang was deprecated in Hugo v0.158.0 and will be removed in a future release.

Man könnte denken, dass sich diese Fehler leicht beheben ließen. Leider können sie sich prima verstecken:

in Submodules, die man als third-party-content lädt (z.B. in Themes). Eine projektweite Suche in der IDE hat Submodules üblicherweise ausgeblendet und liefert keine Treffer.
als Variablen im eigenen Code, die nur indirekt auf die alten Parameter zugreifen: Ich benutze bis dato .Page.Site.Home.AllTranslations, um herauszufinden, ob ich mich auf einer gegebenen Seite in der “Hauptsprache” aufhalte. Allein schon das Scoping ist widersinnig und wird meiner Meinung nach zu Recht entfernt. Das, was ich tun will, kann nun viel einfacher erreicht werden mit .Page.Language.IsDefault

Submodules auf Stand bringen

Bei den Submodulen sehe ich zwei Lösungsansätze:

Die Maintainer anschreiben (bzw. ein Issue aufmachen), dass ihr Code gerade veraltet und sie darum bitten, ihre Themes auf Stand zu bringen.
Die betroffenen Dateien aus dem Submodule herauskopieren und in die eigene Ordnerstruktur integrieren. So würde das in meinem Falle betroffene language-menu.html unter /layouts/partials/language-menu.html eine neue Heimat finden. Dort behebe ich dann die Probleme selbst.

Eigene Lösungen programmieren

Macht die Fehlermeldung keine Lösung offensichtlich, so kann man sich gut an der Hugo Community orientieren. Für die Deprecatoins in v0.158 gibt es beispielsweise eine ausführliche Dokumentation.

Versionen abgleichen

Hmm. Wie das Bild zeigt, verwendet mein Container das Paket hugo extended von hugomods, welches die Version v0.154.5 bereitstellt; ich hatte einen stabilen release für die Action ausgewählt. Vergleichen wir mal mit meiner lokalen Version, die inzwischen ohne auch nur eine Warnung brav baut:

➜ blog git:(main) ✗ hugo version
hugo v0.162.1+extended linux/amd64

Der Klassiker: Es gibt eine Änderung ab v0.158, die die interne API verändert. Ältere Versionen kennen die neuen Felder nicht und meckern. Neuere Versionen hingegen kreiden die Verwendung der alten Felder an.

Ich glaube, diese Probleme lassen sich nur dann zuverlässig vermeiden, wenn die Pipeline für lokal und remote identisch ist. Sprich: Auf dem Lokalen Rechner eine virtuelle Maschine mit dem CI-Betriebssystem booten und alles in Docker wegkapseln. Macht bestimmt Sinn, wenn man in einer größeren Organisation arbeitet und mehrere User vor diesem Problem stehen.

Stattdessen wechsle ich zur Behebung im Remote Container auf die Version image: hugomods/hugo:latest und behebe damit den Fehler. Jedoch habe ich noch immer unterschiedliche Versionen lokal und in der CD-Pipeline. Für mein Betriebssystem gibt es die neueste schlicht noch nicht und auch der Docker Release hängt zeitlich etwas hinter den Releases des Originals.

Die Bau- und Releasezeiten sind fantastisch, oder? Eine Änderung an der Website in 12 Sekunden online zu haben, inkl. Container hochziehen etc. - das gab es bei mir jedenfalls noch nie. Um die 20 Sekunden benötigt der Durchlauf, wenn er die Container refs erst neu holen und herunterladen muss, z.B. bei Updates der Registry von latest.

Einen detaillierten Benchmarkd zwischen Hugo und Jekyll bietet der verlinkte Artikel.

Schallberts Blog mit Hugo

Schallbert — Sun, 06 Sep 2026

Was ist geschehen?

Zum fünften Geburtstag 🥳 stelle ich schallbert’s Blog auf eine neue technische Basis!

Ich habe diesen Blog von jekyll nun auf den Webseitengenerator Hugo umgezogen. Das war viel Aufwand: Über etwa vier Monate hinweg habe ich einen Großteil meiner Freizeit hineingesteckt. Dabei ging der Löwenanteil in das Erstellen und Polieren der Formatierung, Anpassung meiner Inhalte an die neue Umgebung, Reparatur defekter Links und die Dokumentation meines Umbaus.

Warum habe ich das gemacht?

Mit Jekyll stand ich immer mehr auf Kriegsfuß: Viele Abhängigkeiten mit immer häufigeren Defekten, die zunehmend lange Bauzeit und die komplexe Umgebung zum Ausrollen auf meinem Server waren die Hauptgründe.

Meine Seite baut nun etwa fünf mal so schnell wie vorher.

Sie lädt weniger Formatierung nach (CSS, JS) und die Bilder sind noch einmal platzsparender.

Außerdem habe ich weder Ruby noch zig Gems auf Stand zu halten.

Bei den Themes habe ich in Hugo Wert darauf gelegt, es nach benötigter Funktion auszuwählen und nicht nur nach gefälligem Aussehen. Somit ist es jetzt viel simpler und performanter.

Was haben die LeserInnen davon?

RSS logo ^[1]

Der Blog bietet nun einen RSS-Feed. Außerdem sind nun auch meine Projekte in die Schlagwort-Ansicht mit eingebunden. Zu guter Letzt sind durch die Migration zahlreiche Artikel entstanden. Diese sollen einen solchen Umzug für andere leichter machen als ich es hatte, und die Strukturen in Hugo verdeutlichen.

Artikel zum Thema

Was fehlt noch?

Ich bin mit dem Umbau noch nicht ganz fertig:

Die Website auch für die mobile Darstellung optimieren ✓
Es soll möglich sein, Bilder zentriert und in nativer Auflösung anzuzeigen ✓
Der Feed soll Coverbilder meiner Artikel korrekt anzeigen ✓
Ich möchte in CSS einen noch einheitlicheren Look haben (Farben, Bildränder etc.)
Übersichtsseiten könnten die ganze Bildschirmseite einnehmen und dann größere Bilder anzeigen
Es fehlen einige englische Übersetzungen ✓
Schlagworte könnten spezifischer und trennschärfer implementiert werden
Schön wäre ein mitscrollendes Inhaltsverzeichnis auf der linken Seite

Auf diesen Seiten wird es in den kommende Wochen in vielen Details noch einmal Verbesserungen geben. Ich freue mich darauf!

schallbert

Umzug von Jekyll zu Hugo

Schallbert — Sun, 06 Sep 2026

Projekt-Steckbrief

Schwierigkeitsgrad: Mittel 3/5
Kosten: 0€
Zeit ~20h

In diesem Projekt beschreibe ich meinen Umzug von Jekyll mit der Optik von Minimal Mistakes zu Hugo in einem stark modifizierten Terminal-Theme.

Warum überhaupt wechseln?

Schon seit langem war ich nicht mehr vollständig zufrieden mit dem Bauen meiner Website per Jekyll. Der Auslöser für den Umstieg war, dass ich eines Tages plötzlich wegen eines Kompatibilitätsproblemes nicht mehr lokal bauen konnte. Ein bundle update --conservative oder bundle install wie üblich half nicht. Auch das manuelle Nachinstallieren der verursachenden Pakete per gem install commonmarker-0.23.12 oder gem install posix-spawn -v 0.3.15 -- --with-cflags=\"-Wno-incompatible-function-pointer-types\" brachten keine Abhilfe.

Ein Update von Ruby und Jekyll selbst brachte ebenfalls keinen Erfolg. Und überhaupt: Die Bauzeit mit Jekyll ist inzwischen ziemlich lang geworden. Ich bin durch meinen Umzug der Seite von Github Pages auf einen eigenen Server nicht mehr an Jekyll gebunden, was einen Wechsel attraktiver macht.

Weitere Schwierigkeiten mit Jekyll

CI/CD: Meine Deploy-Pipeline war vor Monaten mit ähnlichen Fehlern ausgefallen, sodass ich auf eine ältere Jekyll-Version zurückgreifen musste. Damit vergrößert sich technische Schuld und Angriffsfläche meiner Actions. Ich müsste auf die Suche nach einer gut gewarteten Containerlösung eines anderen Anbieters wechseln. Suche und Einrichtung würden zusätzliche Zeit erfordern.
RSS-Feed: Ich möchte zu meiner Website gern einen RSS-Feed bereitstellen. Meine Experimente mit Jekyll zeigten jedoch, dass nur “Posts” und keine “Announcements” inkludiert werden. Das wollte ich beheben.
Bildformate: Cover-Bilder (Thumbnails) für Posts werden im RSS-Feed durch Jekyll eigentlich mit gebaut. Durch meinen Umstieg von .jpg auf das platzsparendere .avif funktionierte das nun leider nicht mehr. Eine Lösung habe ich trotz mehrerer Anläufe nicht durch den Pull Request Review bekommen.
Icons: Das von mir verwendete Theme nutzt Font Awesome zur Darstellung von Icons und ist insgesamt für eine statische Website recht groß. Ich wollte aber nichts aus dem Netz nachladen und habe die Bibliothek daher lokal gespeichert. Daher war mein Plan, nur die wirklich benötigten Icons heraussuchen und den Rest zu löschen. Mit dem Umstieg auf Hugo ist dies nicht mehr notwendig.

Die Chancen

Von Hugo verspreche ich mir schnellere Bauzeiten, eine vereinfachte CI/CD ohne Nachinstallieren von Bundler, Ruby etc. und die Behebung der oben beschriebenen Schwierigkeiten. Das Abhängigkeits- und Paketmanagement von Hugo unterscheidet sich grundlegend von Jekyll: Zusätzliche Inhalte werden per Git Submodules eingebunden und das Abhängigkeismanagement nutzt statt der Gemfile schlicht Go modules.

Das Migrationswerkzeug

Die Ordnerstrukturen der Inhalte unterscheidet sich deutlich zwischen Jekyll und Hugo. Ich nutze daher ein in Hugo enthaltenes Importwerkzeug, welches mir zumindest die Artikel unter /posts korrekt importiert.

Alle spezifischen Inhalte wie Übersichtsseiten /tags, /pages/error, /pages/legal und Seiten, wo Projekte und Ankündigungen abgelegt sind /_announcements, /_projects, werden allerdings nicht mit umgezogen und müssen manuell kopiert und modifiziert werden.

Anpassen der Front Matter

Viele von mir gemachten Anpassungen in Jekyll funktionieren in Hugo entweder nicht richtig oder führen zum Abbruch des Bauvorganges - die Front Matter einer jeden Markdown-Datei muss also angepasst und teils bereinigt werden.

---
# Alt: So kann die Front matter einer Übersichtsseite in Jekyll aussehen
lang: de
title: Beitragsarchiv
subtitle: Diese Sammlung enthält alle meine Beiträge
layout: collection
collection: posts
permalink: /posts-archive/
entries_layout: grid
classes: wide
author_profile: false
---

In meinem Falle liegen einige Theme-abhänigen Parameter im Frontmatter vor wie layout, classes, author_profile. Der lang-Parameter aus meiner Internationalisierungserweiterung in Jekyll ist nicht einmal korrekte Hugo-Syntax: es erwartet die angezeigte Sprache entweder als Feld unter params: lang oder Ordnerweit. Auch andere, an den eigenen Geschmack angepasste Parameter können definiert und unter params mitgegeben werden.

Permalinks finden gar keinen Eingang mehr in die Front matter, stattdessen findet die Konfiguration zentral statt.

Eine Hugo-kompatible front matter kann so aussehen:

---
title: Beitragsarchiv
description: Diese Sammlung enthält alle meine Beiträge
layout: collection
---

Konfiguration des Theme

Eine Basis-Konfiguration meines Themes kann ich mit folgendem Kommando installieren:

➜ blog git:(main) ✗ git submodule add https://github.com/panr/hugo-theme-terminal ./themes/terminal

Zum Aktivieren muss ich es in der Hauptkonfiguration bekannt machen:

# /hugo.toml

# Add it only if you keep the theme in the `themes` directory.
# Remove it if you use the theme as a remote Hugo Module.
theme = "terminal"

Und schon baut Hugo für mich im Terminal-Theme und Originalfarben.

Dies ist nun nicht vertikal zentriert und für meinen Geschmack zu schmal ausgelegt, der Text recht klein und “meine” Blog-Farben sollen ebenfalls anders sein .

Daher erstelle ich eine .css-Datei, die einige Eigenschaften des Basis-Themes überschreibt. Sie muss im Ordner /static liegen und den Namen des Themes tragen.

/* /static/terminal.css */

:root{
 --background: #252a34;
 --background-highlight: #475064;
 --foreground: #d2eaef;
 --foreground-dimmed: #8b9ea2;
 --accent: #25a679;
 --accent-highlight: #79ae9c;
 --radius: 8px;
 --font-size: 1.35rem;
 --line-height: 1.8em;
}

/* Use system fonts, reduce transferred kB */
body{
 font-family: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif !important; 
}

/* make content wider */
body .container{
 max-width: 70rem;
 width: 90%;
}

Und schon sieht es fast wie früher aus.

Organisation der Ordnerstruktur

Anders als bei der von mir verwendeten Jekyll-Version verfügt hugo über eingebaute Internationalisierung (i18n). Dafür muss ich meine Ordnerstruktur umbauen und explizit in /de und /en-Ordnerinhalte sortieren. Inhalte werden nun statt auf der höheren Ordner-Ebene direkt unter /_pages, /_announcements, /_posts im Ordner content gehalten, was die Sache übersichtlicher macht.

Vorher

.
├── _announcements
├── assets
│ ├── css
│ │ ├── fontawesome
│ │ ├── katex
│ │ ├── main.scss # <-- theme import, customization
│ │ └── webfonts
│ ├── js
│ │ ├── lunr
│ │ ├── _main.js
│ │ ├── main.min.js
│ │ ├── plugins
│ │ └── vendor
│ └── video
├── banner.js
├── CNAME
├── _config.yml
├── _data
│ ├── de
│ │ ├── l10n.yml
│ └── en
│ ├── l10n.yml
├── en
│ └── index.html
├── Gemfile
├── Gemfile.lock
├── _includes # <-- Layouts (HTML), partials, 3rd-party
├── index.html # <-- Landing page
├── _layouts # <-- Page layouts
├── _pages
│ ├── 404.md # <-- German version
│ ├── [...]
│ ├── en
│ │ ├── 404.md # <-- English version
│ │ ├── [...]
├── _posts/
│ └── en 
├── _projects/
├── _sass
│ ├── minimal-mistakes # <-- Styles (SCSS) for layouts and partials
│ ├── minimal-mistakes.scss
│ └── _video.scss
├── _site/ # <-- Build artifacts
├── staticman.yml

Nachher

Einen guten Überblick über die Ordnerstruktur bietet Hugos Dokumentation. Am wichtigsten für die tägliche Arbeit mit Artikeln und Aussehen der Website sind die Stammordner content, layouts und static.

.
├── archetypes
├── assets
├── content
│ ├── de
│ │ ├── about.md
│ │ ├── announcements/
│ │ ├── posts/
│ │ └── projects/
│ └── en
│ ├── about.md
│ ├── [...]
├── data
├── hugo.yml
├── layouts
│ ├── _default
│ │ ├── baseof.html # <-- defines header, add-ons, content, footer structure
│ │ ├── index.html # <-- landing page
│ │ ├── list.html # <-- grid view
│ │ └── single.html # <-- post view
│ ├── _markup
│ │ └── render-link.html # <-- link highlighting and function (referrer, tabs)
│ ├── _partials
│ │ ├── cover.html # <-- cover (thumbnail) image rendering
│ │ └── math.html # <-- math rendering (katex)
│ └── _shortcodes
│ ├── audio.html
│ ├── image.html
│ └── [...]
├── resources
│ └── _gen
│ └── assets/
├── static
│ ├── assets
│ │ ├── audio/
│ │ ├── css/ # <-- contains overrides for custom layouts 
│ │ ├── docs/
│ │ ├── images/
│ │ ├── js/ # <-- math (katex) JS lives here
│ │ └── video/
│ └── terminal.css # <-- Central theme override (colors, formatting, styling)
└── themes
 └── terminal # <-- GIT submodule: Vanilla "Terminal" theme

Bei beiden Lösungen werden Layouts in html und Stil/Format ind CSS definiert. Da ich bei Jekyll mehr Plugins verwenden musste, wird das Setup größer.

Manuelle Anpassungen: Shortcodes

Mit Shortcodes kann man in Hugo nicht-Text-Inhalte (Medien, Links, Formatierung, Stil) definieren, die dann nach definierter Vorschrift gerendert werden. Dafür legt man eine html-Datei an, welche den Dekorator definiert und entsprechende css-Klassen einbindet. Außerdem fügt man die gewünschte Formatierung in der überschreibenden Theme-css-Datei ein.

Da ich hier absolut kein Profi bin, probiere ich anschließend so lange herum, bis mir das Layouting gefällt und ich keine Artefakte/Überlagerungen mehr sehe.

.
├── layouts
│ └── _shortcodes
│ └── my-shortcode.html # <-- Custom shortcode file
├── static
│ └── terminal.css # <-- Central theme override (colors, formatting, styling)

Syntax: Hugo und Jekyll

Shortcodes werden bei Hugo in der Markdown-Datei mit folgender Syntax angezeigt:

{{< shortcode-html-filename options >}}
{{< image src="/path/to/image.avif" alt="Image: alt text" position="right" >}}

Im Vergleich dazu sehen Shortcode-ähnliche Dekoratoren in Jekyll für Liquid, die in Jekyll benutzte Beschreibungssprache so aus:

### Liquid in interpreter code
{% Liquid bracket syntax %}
### Liquid "shortcode" pendant
{% include gallery id="gallery" caption="Eindrücke von **MobFobAmp**. Zum Vergrößern anklicken." %}
### Liquid decorator for layouting
{:.list-inline}

image

Anwendungsbeispiel zur Bildanzeige. In der nächsten Zeile folgt ein zentriertes Bild.

Der klassische Bild-Dekorator für Markdown [Alt Text](/path/to/image) wird in Hugo standardmäßig als mittig zentriertes Bild ohne Textfluss gerendert. Für ein schönes Layouting benötige ich jedoch ein paar Varianten, welche etwas zusätzlichen Code in cascading style sheets und html erfordern.

Bild zentriert, ohne Textfluss
Bild links , Textfluss rechts
Bild rechts, Textfluss links

Zuerst besorgt sich Hugo Dateipfad und Bildtext. Anschließend liest es die gewünschte Formatierung aus der Markdown-Datei, welche mit der position-Variable angelegt wird. Anschließend wendet sie die image-wrapper Klasse aus der .css-Datei darauf an. Die Ausrichtung der Bilder gilt für bessere Lesbarkeit nur für die Desktop-Variante der Webseite (>684px).

Die Anpassungen des Themes gehen zur richtigen Darstellung von Bildern recht weit. Außerdem habe ich noch eine Galerie entwickelt, falls ein Post über sehr viele Bilder verfügt. Daher habe ich für die Bildformatierung und -Ausrichtung einen eigenen Artikel geschrieben.

audio

Zur Darstellung des Audio-Players verwende ich die im Browser implementierten Standards.

Your browser does not support the audio element.

Beispielplayer: Melodie auf dem E-Bass

{{- /* /layouts/_shortcodes/audio.html */ -}}

{{ $src := .Get "src" }}
{{ $caption := .Get "caption" | default "" }}

<div class="media-wrapper">
 <div class="media-container">
 <audio controls>
 <source src="{{ $src }}" type="audio/mp3">
 Your browser does not support the audio element.
 </audio>
 {{ with $caption }}
 <div class="media-title">{{ . }}</div>
 {{ end }}
 </div>
</div>

In css verwende ich einen Wrapper und Media-Container, um Titel im Rahmen des Players anzeigen zu können und die Formatierung zu erleichtern. Auch hier habe ich angepasstes Verhalten für ein “responsive layout” bei Mobilgeräten oder Änderungen der Größe des Browser-Fensters.

video

Das CSS ist identisch mit audio. Es gibt nur im html geringfügige Unterschiede. Der von mir verwendete Container unterstützt unter src= als Quellen sowohl “embed-Links” von Webseiten wie peertube als auch lokale Quelldateien.

Your browser does not support the video tag.

Video-Beispiel (lokal): Linearführungen mit Kugelumlauf

{{- /* /layouts/_shortcodes/video.html */ -}}

{{- $src := .Get "src" -}}
{{- $title := .Get "title" | default "" -}}
{{- $caption := .Get "caption" | default "" -}}

<div class="media-wrapper">
 <div class="media-container">
 {{- if hasPrefix $src "http" -}}
 <iframe src="{{ $src }}" frameborder="0" allowfullscreen></iframe>
 {{- else -}}
 <video controls>
 <source src="{{ $src }}" type="video/mp4">
 Your browser does not support the video tag.
 </video>
 {{- end -}}

 {{- if or $title $caption -}}
 <div class="media-title">
 {{- if $title -}}{{ $title }}{{- else -}}{{ $caption }}{{- end -}}
 </div>
 {{- end -}}
 </div>
</div>

Updates

Auch bei mir “altern” Inhalte. Manchmal wechsle ich Technologien oder Anbieter, und manchmal bewegen sich auch Dritte von Lösungen weg, deren Implementierung ich hier im Blog beschrieben habe. Daher habe ich update-shortcodes eingeführt.

Verlinkungen

Folgendes Verhalten wünsche ich mir für Links auf meinem Blog:

interne Links sollen im selben Tab geöffnet werden und die Nutzer weiterleiten.
interne Links sollen zu Seiten in derselben Sprache verweisen und nicht auf die Standard-Sprache oder zurück zur Hauptseite führen.
externe Links sollen mit einem Symbol gekennzeichnet werden: ↗
externe Links sollen in einem frischen Tab geöffnet werden: target="_blank"
exterme Links sollen weder auf die ursprünglichen Inhalte zugreifen noch den Quellverweis sehen können rel="noopener noreferrer"

Dafür erstelle ich unter /layouts/_markup die Datei render-link.html. Den Code hierfür und seine Hintergründe stelle ich in einem separaten Post vor: Hugo Multi-language: Interne Permalinks

Der Override für CSS sieht wie folgt aus.

/* /static/terminal.css */

.external-link .external-link-icon{
 display: inline-block;
 font-size: var(--font-size);
 vertical-align: middle;
 transform: translateY(-0.1em);
}

Manuelle Anpassungen: Partials

Partials kann man sich vorstellen wie die Layout-Bausteine für eine Hugo-Website. Sie werden unter /layouts/_partials abgelegt und überschreiben die Standards des verwendeten Themes. Dabei wird die Ursprungsdatei gar nicht mehr geladen, was ein Herüberkopieren der Originaldatei in den Ordner mit anschließender manueller Anpassung empfehlenswert macht.

index

Die Startseite für den Blog ist komplett selbt geschrieben und liegt nicht in Markdown, sondern in html vor. Sie zeigt ihre Inhalte anders an als alle anderen Blog-Seiten und daher lohnte es sich für mich nicht, Templates zu programmieren. In der entsprechenden /layouts/_partials/index.html lade ich dafür notwendige scss und css-Dateien und gebe die Struktur der Seite vor. Die folgende Tabelle gibt einen Überblick über meine Änderungen.

File	Purpose	Customization
cover	thumbnail / cover image for overview pages, lists, and grids	Add custom cover image decorator, alt text
head	Defines Favicon, search console, page parameters, feeds etc.	Custom favicon path
header	Page header containing menu, logo, navigation etc.	Add logo and subtitle to menu, lang selector
logo	Custom page logo, title, subtitle	Full
math	Displays math content with Latex/Katex	None, implement math support

math

Mein Blog soll mathematische Notation unterstützen. Dafür benutze ich Katex

{{- /* /layouts/_partials/math.html */ -}}

<link rel="stylesheet" href="/assets/css/katex.min.css">
<script defer src="/assets/js/katex.min.js"></script>
<script defer src="/assets/js/contrib/auto-render.min.js" onload="renderMathInElement(document.body);"></script>

<script>
 document.addEventListener("DOMContentLoaded", function() {
 renderMathInElement(document.body, {
 delimiters: [
 {left: '\\[', right: '\\]', display: true}, // block
 {left: '$$', right: '$$', display: true}, // block
 {left: '\\(', right: '\\)', display: false}, // inline
 ],
 throwOnError : false
 });
 });
</script>

cover image

Unter der Bezeichnung cover verstehe ich ein Titelbild eines Blog-Posts. Es wird in Übersichtsseiten, Artikel- und Tag-Listen etc. angezeigt und soll die Inhalte des Blog-posts unterstützend beschreiben. Auch mein RSS-Feed soll diese Bilder für die Übersicht verschiedener Artikel auf Endgeräten meiner Leserschaft verwenden.

Es ist besonders stark komprimiert und benötigt wenig Übertragungsbandbreite. Daher ist seine Auflösung gering (440x220 oder 640x352). Für einen einheitlichen Look sind sie zudem stets monochrom.

Die Markdown-Syntax zum Einbinden des Covers sehe ich wie folgt vor:

---
cover_alt: 'Image: Hugo console build output. It shows a full build time below 2sec. (~90% reduction over build time with Jekyll)'
cover: /assets/images/migrating-hugo-to-jekyll/hugo-jekyll-build-compare-cover.avif
---

Anschließend erstelle ich unter layouts/_partials die Datei cover.html und schreibe folgenden Code hinein:

{{- /* /layouts/_partials/cover.html */ -}}

{{- /* Handles cover-image generation */ -}}

{{- $cover := false -}}
{{- $autoCover := default $.Site.Params.autoCover false }}

{{- if index .Params "cover" -}}
 {{- if .Resources.GetMatch .Params.Cover }}
 {{- $cover = (.Resources.GetMatch .Params.Cover).RelPermalink -}}
 {{- else -}}
 {{- $cover = absURL .Params.Cover -}}
 {{- end -}}
{{- else if $.Site.Params.AutoCover -}}
 {{- if (not .Params.Cover) -}}
 {{- if .Resources.GetMatch "cover.*" -}}
 {{- $cover = (.Resources.GetMatch "cover.*").RelPermalink -}}
 {{- end -}}
 {{- end -}}
{{- end -}}

{{if $cover -}}
 <!-- Cover image found -->
 <img src="{{ $cover }}"
 class="post-cover"
 alt="{{ .Params.cover_alt | plainify | default (.Description| plainify) }}"
 title="{{ .Params.CoverCredit |plainify|default (.Title | plainify) }}" />
{{- end }}

Der Code sucht und extrahiert den Pfad zum Coverbild. Sollte ein valider Pfad gefunden werden, wird es als post-cover mit entsprechendem CSS angezeigt.

Dem XML-Template füge ich als erstes Element innerhalb des <description>-Tags das Coverbild hinzu. Erst danach kommt der eigentliche Artikel. Die meisten Feed Reader nehmen dieses Bild dann als Cover für ihre Übersichten.

Manuelle Anpassungen: Layouts

Damit sich meine Seite in Hugo weiterhin ganz ähnlich anfüllt wie zuvor in Jekyll muss ich in den Layouts ein paar Änderungen vornehmen. Im Folgenden habe ich sie beschrieben.

baseof.html

Hier werden die Basis-Inhalte definiert. Definitionen für Kopf- und Fußzeile werden importiert und Stylesheets eingebunden. Die allermeisten oben beschriebenen Änderungen werden an dieser Stelle importiert.

{{- /* /layouts/baseof.html */ -}}

<!DOCTYPE html>
<html lang="{{ $.Site.Language }}">
<head>
 {{ if .Param "math" }}
 {{ partialCached "math.html" . }}
 {{ end }}
 {{ block "title" . }}
 <title>{{ if .IsHome }}{{ $.Site.Title }}{{ else }}{{ .Title }} :: {{ $.Site.Title }}{{ end }}</title>
 {{ end }}
 {{ partial "head.html" . }}
 <link rel="stylesheet" href="{{ "/assets/css/gallery.css" | relURL }}"> 
 <link rel="stylesheet" href="{{ "/assets/css/media.css" | relURL }}">
</head>
<body>
{{ $container := cond ($.Site.Params.FullWidthTheme | default false) "container full" (cond ($.Site.Params.CenterTheme | default false) "container center" "container") }}

<div class="{{- $container -}}{{- cond ($.Site.Params.oneHeadingSize | default false) " headings--one-size" "" }}">

 {{ partial "header.html" . }}

 <div class="content">
 {{ block "main" . }}
 {{ end }}
 </div>

 {{ block "footer" . }}
 {{ partial "footer.html" . }}
 {{ end }}
</div>

</body>
</html>

list.html

Für Übersichtsseiten wie Artikel, Tags, Projekte benötige ich eine Listenansicht. Dabei möchte ich je vier Artikel in einer Zeile anzeigen. Jeder Artikel bekommt ein eigenes “Kärtchen” mit Titelbild (cover), Titel, Kurzbeschreibung und - falls Verfügbar - weiteren Details wie Lesezeit. Hugos paginator crawlt den entsprechenden Ordner und stellt die Inhalte zusammen, wärend mein Stylesheet list.css Formatierung und Anzeige übernimmt.

{{- /* /layouts/_default/list.html */ -}}

{{ define "main" }}
 <link rel="stylesheet" href="{{ "/assets/css/list.css" | relURL }}">
 {{ with .Content }}
 <div class="index-content">
 {{ . }}
 </div>
 {{ end }}

 <div class="posts posts-grid">
 {{ range .Paginator.Pages }}
 <article class="post on-list">
 <a href="{{ .Permalink }}" class="post-card" aria-label="{{ .Title }}">
 {{ partial "cover.html" . }}

 <div class="post-card-body">
 <h4 class="post-title">
 {{ .Title | markdownify }}
 </h4>

 <div class="post-excerpt">
 {{ if .Description }}
 <p>{{ .Description }}</p>
 {{ end }}
 </div>

 {{- if and (.Param "readingTime") (eq (.Param "readingTime") true) -}}
 <div class="post-reading-time">
 {{ .ReadingTime }} {{ $.Site.Params.minuteReadingTime | default "min read" }}
 </div>
 {{- end -}}
 </div>
 </a>
 </article>
 {{ end }}

 {{ partial "pagination.html" . }}
 </div>
{{ end }}

single.html

Meine single,html ist fast identisch mit der Standardimplementierung von terminal. Ich habe lediglich die Möglichkeit hinzugefügt, ein zum Titel gehöriges “banner-image” zu haben, und importiere die _partial/cover.html-Vorschrift zum Laden eines Coverbildes.

<article class="post">
 {{ with .Params.banner }}
 <img
 src="{{ . }}"
 class="post-banner"
 alt="{{ $.Params.banner_alt | plainify | default ' ' }}"
 />
 {{ end }}

Bei all den Änderungen könnte man überlegen, ein eigenes Theme zu forken… 🤔

Qualitätskontrolle

Neu ist für meine Website auch, dass ich auf tote Links prüfe. Die Seite ist erwachsen geworden und verfügt über so viele interne und externe Verlinkungen, dass dies manuell nicht mehr sinnvoll durchzuführen ist. Mit welchem Tool ich vorgehe und wie ich dabei Hugo-Eigenheiten berücksichtige, dokumentiert der Artikel zum Thema htmltest-Konfiguration für Hugo.

Veröffentlichung

Auch für Hugo benötige ich eine automatisierte Pipeline. Sobald ich eine Änderung nach main schiebe, soll die Webseite automatisch neu gebaut und ausgeliefert werden. Wie das genau funktioniert beschreibe ich im Artikel Hugo-Website mit Github Actions in Docker bauen und ausliefern.

Leistung

Was der ganze Aufwand jetzt gebracht hat? Für user ist Aussehen und Navigation sehr ähnlich zur Website in Jekyll. Die Verbesserungen machen sich allerdings durch schnellere Ladezeiten, geringere zu übertragende Datenmengen und bessere Übersichtlichkeit aus. Einendetaillierten Vergleich zwischen nehme ich im Artikel Jekyll vs. Hugo Benchmarking vor.

Hugo: Bilder im Textfluss ausrichten

Schallbert — Sat, 29 Aug 2026

Warum das Ganze?

Mein Theme kann aus dem klassischen Markdown ![Image Alt Text](/path/to/image/) keine Bildformatierung und -Positionierung ableiten. Das benötige ich aber, um Bilder links, mittig, und rechts zu platzieren - mit und ohne Textfluss. Also muss ich selbst ran und mir etwas programmieren.

Einstieg in shortcodes, layouts, css

Einen Überblick verschaffe ich mir auf cshire und stelle schnell fest, dass mein erster Versuch per /layouts/render-image.html nicht funktioniert.

Debugging

Auf diese Weise stelle ich fest, ob render-image.html überhaupt gelesen und angewendet wird - und zwar unabhängig von CSS:

<div style="border: 3px dashed red; padding: 10px; margin: 10px; font-weight: bold;">
 RENDER-IMAGE.HTML IS BEING READ!
</div>

Das funktioniert. Also muss Hugo irgendwas in der Markdown-Verarbeitung entgehen.

Ursachenbehebung

Ich sehe nun, dass Hugo zwar das Layout rendert, meine Bilder aber nicht richtig auswertet. Warum? Weil zur Auswertung der Bilder ein Auslöser, genannt shortcode, fehlt. Shortcodes in Hugo werden mit {{ <shortcode-name> parameter1="String" parametern="string" }} im Markdown angelegt, mittels der entsprechenden Vorschrift /layouts/shortcodes/<shortcode-name>.html ausgewertet und anschließend durch CSS interpretiert dargestellt.

Shortcode: image.html

Ich habe mir also ein Shortcode-Template gebastelt, sodass ich dem Bild ein paar weitere Parameter zusätzlich zu Quelldatei src und Alternativtext alt mitgeben kann: position, caption, attrid, attrlink. Position und Titel des Bildes sind selbsterklärend. Eine Attributionsmöglichkeit wollte ich für nicht selbsterstellte Bilder haben. Bei diesen greife ich entweder auf offene Inhalte unter Rechtsverhältnissen wie den creative commons zu oder besorge mir vorab das schriftliche Einverständnis der Urheberrechtsinhaberschaft.

{{- /* layouts/_shortcodes/image.html */ -}}

{{- $src := .Get "src" -}}
{{- $alt := .Get "alt" | default "" -}}
{{- $position := .Get "position" | default "center" -}}
{{- $caption := .Get "caption" -}}
{{- $attrid := .Get "attrid" -}}
{{- $attrlink := .Get "attrlink" -}}

<figure class="media-frame media-frame--{{ $position }}">
 <img src="{{ $src }}" alt="{{ $alt }}">

 {{- if $caption -}}
 <figcaption class="media-caption">
 <span class="caption-text">{{ $caption }}</span>
 {{- if and $attrid $attrlink -}}
 <a
 href="{{ $attrlink }}"
 class="attr-link"
 aria-label="Attribution {{ $attrid }}"
 >
 <sup class="attr-id">[{{ $attrid }}]</sup>
 </a>
 {{- end -}}
 </figcaption>
 {{- end -}}
</figure>

Diese Vorlage liest die mitgegebenen Parameter aus dem Shortcode aus und packt das Bild <img> in einen Rahmen <figure class="media-frame">. Dieser trägt die Positionsinformation. Sofern ein Bildtitel und/oder eine Attribution vorliegt, wird dies in der figcaption class="media-caption" abgebildet.

Verwendung des Shortcodes

In Markdown würde ein Bild mit “Vollausstattung” nun so aussehen:

{{< image src="/path/to/image.jpg" 
alt="Example placeholder image for shortcode demonstration purposes" 
caption="Shortcode demo image" 
attrid="1" attrlink="https://example.com/" 
position="right" >}}

Migration

Nur wie komme ich jetzt von den bisher von mir in Jekyll verwendeten ![alt](/path/to/image) {: .align-center} in das oben angegebene Format?

Mit einem Skript! Dafür erstelle ich mir ein python-Programm, welches durch jeden meiner Artikel kämmt und dort nach Bildern in der oben angegebenen Formatierung sucht. Bei einem Treffer extrahiert es src, alt, position und ersetzt den kompletten Ausdruck zu einem Hugo-Shortcode-Äquivalent.

import os
import re
from pathlib import Path

# spaces/tabs only, no newlines
SPACES = r'[ \t]*'

IMG_WITH_OPTIONAL_ALIGN = re.compile(
 r'!\[([^\]]*?)\]\(([^)]*?)\)' # alt, src
 + SPACES + # optional spaces/tabs before decorator
 r'(?:\{:' + SPACES + # literal "{:"
 r'[^}\n]*?\.align-(center|left|right)\b[^}\n]*?' # decorator body (no newlines)
 r'\})?' # optional "}"
)

def convert_image_alignments(directory):
 def repl(m):
 alt = m.group(1).replace('"', "'")
 src = m.group(2)
 position = m.group(3) or ''
 # return built Hugo shortcode. Escape Python f-string curly brace { with {{.
 return f'{{{{< image src="{src}" alt="{alt}" position="{position}" >}}}}'

 for root, _, files in os.walk(directory):
 for file in files:
 if not file.endswith('.md'):
 continue

 filepath = Path(root) / file
 content = filepath.read_text(encoding='utf-8')

 new_content = IMG_WITH_OPTIONAL_ALIGN.sub(repl, content)
 if new_content != content:
 filepath.write_text(new_content, encoding='utf-8')
 print(f"Updated: {filepath}")

if __name__ == "__main__":
 project_root = input("Enter the path to your project root: ").strip()
 if os.path.isdir(project_root):
 convert_image_alignments(project_root)
 print("Conversion complete!")
 else:
 print("Invalid directory path.")

Bei den Regexes habe ich mir von Mistral helfen lassen, ansonsten ist das Skript aber einfach gehalten.

Bilder mit Titel und/oder Attribution waren in Jekyll als figure deklariert. Auch für diese schreibe ich ein ganz ähnliches Skript und lasse es bei der Migration durchlaufen.

CSS

Kommen wir zur Darstellung der Bilder. Ich erstelle eine seitenfüllende CSS-Datei /assets/css/media.css, welche außerdem Größe und Formatierung anderer eingebetteter Medien wie Audio- und Videodateien einheitlich sowohl für die mobile- als auch die Desktopansicht regeln soll. Dafür greift sie auf die in der Vorlage definierten class=-Attribute zu.

Ich nehme zur Erläuterung mal einen Ausschnitt aus der Datei heraus: Hier lege ich das Verhalten des media-frame-Objektes fest. Jedes Asset (Bild, Video, Audio) wird in einem Rahmen eingebettet, welcher der Darstellung die nötige Luft verschafft. Mit dem Attribut position= wird definiert, wo und wie dargestellt werden soll.

Dabei sind die Inhalte standardmäßig zentriert und werden solange sie nicht größer sind als die maximale Textbreite in ihrer nativen Auflösung dargestellt.

.media-frame img,
.media-frame audio,
.media-frame video {
 display: block;
 width: auto;
 max-width: 100%;
 height: auto;

 margin: 0;
 padding: 0;
 border: 0;
 border-radius: 0;
}

.media-frame--center {
 margin-left: auto;
 margin-right: auto;
}

/* Left/Right align only for Non-mobile use */
@media (min-width: 768px) {
 .media-frame--left {
 float: left;
 max-width: 60%;
 margin-top: 0.35em;
 margin-right: 1rem;
 margin-bottom: 0.75rem;
 }

 .media-frame--right {
 float: right;
 max-width: 60%;
 margin-top: 0.35em;
 margin-left: 1rem;
 margin-bottom: 0.75rem;
 }
}

Auf einer Seite ausgerichtete Bilder werden in der Breite begrenzt, denn es soll noch Textfluss drum herum stattfinden. Außerdem werden minimale Abstände zu anderen Objekten definiert, damit sich bei aufeinanderfolgenden Medien nicht Rahmen an Rahmen reibt. In der mobilen Ansicht ist der Platz so beengt, dass Bilder stets zentriert dargestellt werden.

Galerie

Für den Fall, dass ich viele Bilder an einer zentralen Stelle anzeigen will, erstelle ich mir zusätzlich einen gallery-Shortcode und zugehöriges CSS. Die Galerie zeigt Bilder in einem Raster an. Bewegt man die Maus über eines der Bilder, so erscheint es heller als die anderen. Klickt man auf ein Bild, so erscheint es in groß am unteren Rand der Galerie, wobei der oben bereits beschriebene media-Shortcode wiederverwendet wird.

Die darzustellenden Bilder werden in der front matter des Markdown-Dokumentes als Liste per src und alt angelegt. Hier ein Ausschnitt aus der Vorlage zur Auswertung des Shortcodes.

<section class="hugo-gallery">
 <div class="hugo-gallery__frame">
 <div class="hugo-gallery__grid" role="list">
 {{- range $i, $img := $items -}}
 {{- $src := $img.src -}}
 {{- $alt := $img.alt | default (printf "Gallery image %d" (add $i 1)) -}}

 {{- $thumbURL := $src -}}
 {{- $p := strings.TrimPrefix $src "/assets/" -}}

 {{- with resources.Get $p -}}
 {{- $thumb := .Fit "400x220" -}}
 {{- $thumbURL = $thumb.RelPermalink -}}
 {{- end -}}

 <a
 class="hugo-gallery__thumb"
 href="#gallery-full-{{ $i }}"
 aria-label="{{ $alt }}">
 <img
 src="{{ $thumbURL }}"
 alt="{{ $alt }}"
 class="hugo-gallery__thumb-img"
 loading="lazy">
 </a>
 {{- end -}}
 </div>

Ich iteriere durch alle in der Frontmatter definierten Bilder, begrenze ihre Größe auf handliche 400x220px und ordne sie in einem Raster class=hugo-gallery__grid an.

Tests

Das Erstellen der Vorlagen ging verhältnismäßig schnell. Mit CSS stehe ich aber auf Kriegsfuß. Ständig funkt mir irgendein Override aus einer anderen Datei dazwischen oder ich komme mir selbst mit den Styles im Basis-CSS in die Quere. Daher benötige ich einen Ort zum Testen von Formatierung und Anordnung.

Daher habe ich eine Bild-testseite erstellt. Neugierig? Prüfen der Darstellung von Medien in Hugo

htmltest-Konfiguration für Hugo

Schallbert — Mon, 10 Aug 2026

Nun bin ich mit dem Umzug meiner Website zu Hugo fast fertig. Ich musste mehrere Anpassungen in der Frontmatter jedes Artikel vornehmen, damit sie in Hugo ähnliche Funktionen aufweisen wie zuvor mit Jekyll. Es ergaben sich einige Änderungen in der Ordnerstruktur teils durch die Migration, teils auch durch meine Erfahrungen als Autor, sodass auf dem Weg einige Links in praktisch jedem meiner Artikel zu überarbeiten waren. Inzwischen habe ich fast 340 davon, wenn man die Übersetzungen mitzählt.

Der schieren Masse der Links komme ich ohne weitere Hilfsmittel nicht bei. Also benötige ich Werkzeug.

htmltest

Htmltest ist ein Hilfsprogramm, das HTML-Dateien nach Problemen durchsuchen kann. Unter anderem spürt es defekte Links auf. Ich installiere es per

# Red Hat-based Linux package manager install command
sudo dnf install htmltest

und wende es auf die von Hugo “gebauten” HTMl-Dateien im /public-Verzeichnis an:

htmltest public/
# [...]
✘✘✘ failed in 2.890119823s
2612 errors in 337 documents

Das sind aber ganz schön viele Fehler! Die Darreichungsform erscheint mir außerdem ziemlich unübersichtlich, siehe Bild.

Ausgabe in Datei umleiten

Folglich tue ich mich erstmal ziemlich schwer mit diesem Werkzeug. Ich hatte angenommen, dass mir ein paar Links kaputtgegangen sind und nicht mit tausenden Fehlern gerechnet. Also fiel ich dem typischen not-invented-here Syndrom anheim und programmierte selbst ein Werkzeug in python, welches sich im Nachhinein als nicht gut genug entpuppte. Kurzgesagt:

Htmltest ist ein tolles und unglaublich schnelles Werkzeug. Wenn man dessen Ausgabe leserlich macht und richtig deutet, kann man damit ziemlich glücklich werden. Mit ein bisschen Herumprobieren gelange ich zu folgendem Befehl:

htmltest public/ 2>&1 | ansi2html > htmltest-output.html

Bedeutung: “Führe htmltest im /public/-Ordner aus. Leite Fehler aus stderr in die Ausgabe stdout um. Reiche die Ausgabe an ansi2html¹ weiter. Schreibe dessen Ausgabe in eine Datei namens htmltest-output.html.

Das sieht doch so schon viel besser aus!

Fehlerkategorien

Die mit htmltest gefundene Fehler lassen sich für meine Zwecke in ein paar wenige Kategorien sortieren:

Hugo-intern bedingte Fehler wie durch livereload.js verursachte target does not exist-Meldungen.
Unvollständige Links, die zwar in der Praxis funktionieren, aber href lacks trailing slash-Fehler erzeugen. Diese Art Fehler machen bei mir den Löwenanteil der berichteten Probleme aus.
Lookup-Fehler GET <src> [...] failure in name resolution, bei fehlender Verbindung, unzureichenden Rechten, aktiver Bot-Abwehr oder wenn der Zielserver offline ist
Harte, durch defekte Links erzeugte target does not exist-Fehler. Genau diese wollte ich eigentlich beheben.

Das Log bereinigen

Wie bekomme ich nun nur noch Fehler der vierten Kategorie angezeigt? Durch ein paar Änderungen in den Werkeugen und die Beseitigung der Trailing-Slash-Fehler.

Fehler der Kategorie 1, die durch Hugos nützliche livereload-Funktion hervorgerufen werden, sehen so aus:

 target does not exist --- en/tags/tools/index.html --> /livereload.js?mindelay=10&v=2&port=1313&path=livereload

LiveReload ist diejenige Funktion, die mir ständiges F5-Tippen im Browserfenster erspart, wenn Hugo eine meiner Änderungen nach dem Speichern der Markdown-Datei baut. Für den Test kann ich es jedoch kurz deaktivieren. Die folgende Lösung reduziert die Anzahl erzeugter Fehler um eins pro html-Seite.

hugo server --disableLiveReload

Lookup-Fehler der Kategorie 3 vermeide ich durch einen Fokus auf interne Links worüber ich die vollständige Kontrolle habe. Hierbei hilft mir der Parameter -s, --skip-external in htmltest:

htmltest -s public/ 2>&1 | ansi2html > htmltest-output.html
# [...]
✘✘✘ failed in 494.7678ms
446 errors in 337 documents

Tote externe Links kann ich zu einem späteren Zeitpunkt beheben; nun will ich erstmal die durch die Migration entstandenen Probleme lösen.

“Missing trailing slash”: Fehlerbehebung per Markup

Mit den vielen href lacks trailing slash-Fehlern tue ich mich lange zeit schwer, müsste ich doch an fast jeden Markdown-Link in jedem Artikel ein / anfügen. Zum Glück finde ich eine Lösung in meinem Markup render-link.html:

{{- /* /layouts/_markup/render-link.html */ -}}

{{- $url := .Destination | safeURL -}}
{{- $is_external := or (strings.HasPrefix $url "http://") (strings.HasPrefix $url "https://") -}}
{{- $is_anchor := strings.HasPrefix $url "#" -}}
{{- $is_asset := strings.HasPrefix $url "/assets/" -}}

[...]

{{- /* Add / to internal paths that have no file extension */ -}}
{{- if and (not $is_external) (not $is_anchor) (not $is_asset) -}}
 {{- $parsed := urls.Parse $url -}}
 {{- if and $parsed (not (strings.HasSuffix $parsed.Path "/")) (eq (path.Ext $parsed.Path) "") -}}
 {{- $url = printf "%s/" $url -}}
 {{- end -}}
{{- end -}}

[...]

Bedeutung: Interne Links, die weder auf Überschriften is_anchor noch Mediendateien is_asset verweisen, bekommen genau dann ein / angehangen, wenn sie eine korrekte Syntax aufweisen parsed und noch keinen Slash am Ende der URL vorweisen können.

Dies löst 95% der Fehlermeldungen durch weniger hässliches html. Die restlichen 5% hole ich mir durch Anhängen von ein paar Slashes in der Hugo-Konfiguration. Beispiele:

# hugo.yml
url: "/en/" # /en -> /en/ 
logoHomeLink: "/en/" # /en -> /en/

Fertig! Übrig bleiben nur noch harte, interne Fehler.

htmltest -s public/ 2>&1 | ansi2html > htmltest-output.html
# [...]
✘✘✘ failed in 359.28ms
102 errors in 84 documents

Manuelles Suchen und Beheben

Was nun folgt ist reine Fleißarbeit. Ich öffne das Zieldokument (also jenes, auf welches per Link verwiesen wird) und schaue mir an, ob zum Beispiel Überschriftenlinks zwischen verschiedenen Sprachen uneinheitlich sind. Falls ja, füge ich individuelle Anchor-Links an die Überschrift an.

### Überschrift {#heading3}

Falls in der Zieldatei alles paletti ist, öffne ich zusätzlich alle Quelldateien, die den defekten Link verwenden. Dort korrigiere ich den Link manuell. In den meisten Fällen befindet sich die Zieldatei inzwischen in einem anderen Ordner, oder der Sprachpräfix ist falsch gesetzt.

Das Ergebnis

Nach ein paar Stunden anstrengender und dröger Handrbeit werde ich belohnt:

htmltest public/ -s 2>&1
Skipping the checking of external links.
htmltest started at 10:51:23 on public
========================================================================
✔✔✔ passed in 238.970354ms
tested 338 documents

Bald kann ich mit meiner neuen alten Seite online gehen!

ansi2html bzw. colorized-logs ist ein Hilfsprogramm, welches Konsolenausgabe inkl. Formatierung und Textfarben in html umwandelt. ↩︎

Hugo Multi-Lang: Interne Permalinks

Schallbert — Mon, 27 Jul 2026

Wer in Hugo wie ich einen mehrsprachigen Blog baut, könnte folgendes Problem kennen:

Interne Links in Artikeln verschiedener Sprachen verweisen nur auf Seiten in der Standard-Sprache.

Konfiguration

Grundlage für das Problem ist die folgende Einstellung:

# hugo.yml

defaultContentLanguage: "de"
defaultContentLanguageInSubdir: false
disableDefaultLanguageRedirect: true

Meine Standardsprache ist Deutsch und zugehörige Artikel werden in das Hauptverzeichnis des Blogs gebaut. Eine Weiterleitung in das Sprachverzeichnis /de findet nicht statt.

Die Verzeichnisstruktur lautet:

├── content
│ ├── de
│ │ ├── about.md
│ │ ├── announcements
│ │ ├── legal.md
│ │ ├── posts
│ │ ├── privacy.md
│ │ └── projects
│ └── en
│ ├── about.md
│ ├── legal.md
│ ├── posts
│ ├── privacy.md
│ └── projects

Das Problem mit der Standardsprache

Ich halte Artikel durch Nutzung von slug in meiner Standardsprache unter Adressen erreichbar wie example.com/my-post, example.com/my-2nd-post/. In der Zweitsprache hingegen erscheinen sie als example.com/en/my-post, example.com/en/my-2nd-post/.

Wenn ich zwei Artikel nun intern verlinken möchte, dann verweist der Link stets auf den Artikel meiner Standardsprache.

# English version of my post
# example.com/en/my-post
---
slug: my-post

---
Post's English content
[2nd](/my-2nd-post)

Ich erreiche damit statt des gewünschten /en/my-2nd-post nur die deutsche Version /my-2nd-post. Das finde ich blöd, denn so müsste ich jeden Link in allen Artikeln manuell anpassen. Leider scheint Hugo dafür keine eingebaute Lösung mitzubringen. Also erstelle ich mir eine Vorschrift, wie Links gerendert werden sollen:

{{- /* /layouts/_markup/render-link.html */ -}}

Lösung: Sprachabhängige Link-Prefixes

Dort soll folgendes passieren: Wenn beim Bauen ein relativer Link innerhalb der Seite gefunden wird, so ist genau dann ein Sprachpräfix wie /en vor diesen Link zu setzen, wenn die Sprache der zu rendernden Seite nicht der Standardsprache entspricht (denn für letztere benötige ich wegen defaultContentLanguageInSubdir: false keinen Sprachpräfix).

Standardsprache auslesen

Nur wie komme ich an die Standardsprache? Die Parameter defaultContentLanguage sind in Templates nicht zugänglich. Nach längerer Recherche finde ich eine passende Lösung für das Problem in der Hugo community: Die Standardsprache ist meist die erste Sprache des gewichtsbasierten Index (welcher die Sprachen nach Reihenfolge erscheinen lässt): index .Page.Site.Home.AllTranslations 0 Wenn ich diesen nun auslese, ist die “erste” meine Standardsprache.

Code für render-link.html

{{- /* /layouts/_markup/render-link.html */ -}}

{{- $url := .Destination | safeURL -}}
{{- $currentLang := .Page.Language.Locale -}}

{{- $is_external := or (strings.HasPrefix $url "http://") (strings.HasPrefix $url "https://") -}}
{{- $is_anchor := strings.HasPrefix $url "#" -}}
{{- $is_asset := strings.HasPrefix $url "/assets/" -}}
{{- $is_lang_prefixed := strings.HasPrefix $url (printf "/%s/" $currentLang) -}}

{{- if $is_anchor -}}
 {{- $url = printf "%s%s" .Page.RelPermalink $url -}}
{{- else -}}
 {{- if not $is_external -}}
 {{- if and (not $is_lang_prefixed) (not $is_asset) (not .Page.Language.IsDefault) -}}
 {{- $url = printf "/%s%s" $currentLang $url -}}
 {{- end -}}
 {{- end -}}
{{- end -}}

{{- /* Add / to internal paths that have no file extension */ -}}
{{- if and (not $is_external) (not $is_anchor) (not $is_asset) -}}
 {{- $parsed := urls.Parse $url -}}
 {{- if and $parsed (not (strings.HasSuffix $parsed.Path "/")) (eq (path.Ext $parsed.Path) "") -}}
 {{- $url = printf "%s/" $url -}}
 {{- end -}}
{{- end -}}

<a href="{{ $url | relURL }}"{{ if $is_external }} target="_blank" rel="noopener noreferrer" class="external-link"{{ end }}>
 {{- .Text | safeHTML -}}
 {{- if $is_external -}}
 <span class="external-link-icon" aria-hidden="true">↗</span>
 {{- end -}}
</a>

Solange die Standardsprache und der Gewichtsindex übereinstimmen, d.h. die Standardsprache ganz oben auftaucht, funktioniert dies prima.

Zusatzfunktionen

Was der Code sonst noch macht:

Prüfung, ob Links nach “extern”, also von meiner Site weg gehen. Jene bekommen dann ein eigenes Fenster und den Indikator ↗.
Prüfung, ob der Link auf eine Überschrift “anchor” führt. Details dazu siehe unten.
Prüfung, ob der Link zu einer (Medien-)Datei “asset” führt. Asset-Links werden nicht modifiziert.

Handelt es sich um einen Überschriftslink, so wird dieser gegebenenfalls auf die vollständige URL ergänzt. Das geschieht nach folgendem Schema: #heading --> /<opt_lang>/<opt_category>/<title>/#heading

Richtig auflösende Permalinks auf Überschriften

Auch für hochspezielle Permalinks innerhalb einer Seite habe ich eine Lösung gefunden. Nehmen wir an, ich habe verschiedensprachige Überschriften :

---
# German
# content/de/posts/yyyy-mm-dd-hugo-create-language-specific-permalinks.md

description: Mit _markup interne Links richtig routen
title: "Hugo Multi-Lang: Interne Permalinks"
slug: hugo-create-language-specific-permalinks
---

## Richtig auflösende Permalinks auf Überschriften {#permalinks}
Lorem Ipsum...

---
# English
# /content/en/posts/yyyy-mm-dd-hugo-create-language-specific-permalinks.md

description: Routing internal links with _markup
title: "Hugo Multi-Lang: Internal Permalinks"
slug: hugo-create-language-specific-permalinks
---

## Correct Permalinks to headings {#permalinks}
Lorem Ipsum...

Dann sollte ein Klick auf diesen Link zurück zur Überschrift #permalinks sprachunabhängig wieder zurück zur Überschrift führen. Schlüssel für diese Lösung ist das Einführen einer Überschriftsdefinition (Heading-ID) in Markdown, in diesem Fall {#permalinks}.

Funktioniert so noch nicht.

Weil #permalinks auf <blog's baseurl>/#permalinks verweist und somit der Link auf die aktuelle Seite fehlt. Doch auch das bekommen wir hin: Ich erweitere den Link-Renderer um ein paar Zeilen Code und gebe die aktuelle Seiten-URL als Präfix hinzu.

Code für render-link.html mit Unterstützung für Überschriften

{{- $is_anchor := strings.HasPrefix $url "#" -}}

{{- if $is_anchor -}}
 {{- $url = printf "%s%s" .Page.RelPermalink $url -}}
{{- end -}}

Nun wird (#permalinks)erweitert zu /hugo-create-language-specific-permalinks/#permalinks, sodass der Link endlich zum Ziel führt.