Umzug von Jekyll zu Hugo

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.