Serie: Static Site Generators - Hugo (Teil 3)

Inhaltsverzeichnis

1. Einleitung
2. Hugo Teil 1
3. Publii
4. Hugo Teil 2
5. mdBook
6. Hugo Teil 3 (das ist dieser Artikel)
7. Pandoc/Markdown

Im ersten Teil unserer Artikelserie über SSGs habe ich die Einrichtung, Grundstruktur und das Erstellen einer ganz einfachen Website mit Hugo erklärt. Im zweiten Teil ging es um Themes und deren Verwendung. Dieser dritte und letzte Teil widmet sich der Theme-Konfiguration, den Inhalten (neue Seiten und Media-Dateien), der Markdown-Erweiterung und dem Publizieren eurer Website. Falls ihr die bisherigen Teile nicht gelesen habt, empfehle ich, das nachzuholen, weil dieser Teil darauf aufbaut.

Theme-Konfiguration

Abhängig vom verwendeten Theme hat die Konfigurationsdatei die Endung json, toml oder yaml. Im Beispiel aus Teil 2 heisst die Datei hugo.toml. Euch kann es egal sein, welches Format die Datei hat; sie sind sich alle ähnlich. Wichtiger ist ihr Inhalt, weil damit die wesentlichen Einstellungen der Website bestimmt werden. Wie viel ihr darin einstellen könnt, unterscheidet sich von Theme zu Theme. Idealerweise enthält die Theme-Beschreibung auch eine Dokumentation dieser Konfigurationsdatei.

Bei meinem Beispiel-Theme "Split" enthält die hugo.toml eher wenige Einstellmöglichkeiten. Dennoch ist sie zu gross, um sie hier vollständig zu zeigen. Daher beschränke ich mich auf ein paar Ausschnitte. Am Anfang sehen diese Dateien meist sehr ähnlich aus:

# Site settings
baseURL = "https://paulchen.bear"
languageCode = "de-DE"
title = "Paulchen Bär"
theme = "hugo-split-theme"
disableKinds = ["section", "taxonomy", "RSS", "sitemap"]
disableHugoGeneratorInject = true

Viele Parameter sind selbsterklärend. Wichtig ist die baseURL. Falls ihr für eure Site zwischen TEST- und PROD-Umgebung unterscheidet, müsst ihr hier die URL umschalten. Wenn ihr verschiedene Themes verwendet, muss bei theme zwingend der Name des gewünschten Themes stehen. Aber Achtung: Da alle Themes eine eigene Konfigurationsdatei haben, genügt es nicht, den Themenamen in einer einzigen Konfig-Datei zu ändern. Besser ist es, mehrere Dateien zu pflegen und diese je nach Theme durch Namensänderung zu de-/aktivieren.

Beim Split-Theme heisst die Konfigurationsdatei hugo.toml, was ungewöhnlich ist. Normalerweise heisst die Datei config.toml/json/yaml. Ihr könnt die hugo.toml in config.toml umbenennen; danach funktioniert die Generierung weiterhin.

Hier ist ein weiteres Kapitel aus der Konfig-Datei:

[params]

  # Metadata for search engines and social sharing
  author = "Paulchen Bär"
  description = "Split is a centrally-divided layout for a professional online presence with a big image or video left with alongside content."
  shareImage = "images/social.jpg"
  twitterHandle = "onepagelove"

  # Whether you purchased the license from the author.
  licensed = false

  # Favicon
  favicon = "favicon.ico"

  # Section - Visual
  [params.visual]

    # Image
    [params.visual.image]
      enable = true
      file = "images/background.jpg"
      position = "center center"

Auch hier zeigt sich, dass die meisten Parameter selbsterklärend sind.

Neue Seiten

Wie bereits in Teil 2 erläutert, befinden sich die Seiten einer Hugo-Site im Unterverzeichnis content. Da es sich bei "Split" um ein One-Page-Theme handelt, ist es schwierig, mehrere Seiten zu zeigen. Dafür eignen sich Blog-Themes besser. Na ja, egal. Bei Hugo erzeugt man eine neue Inhaltsseite mit dem Befehl: 

hugo new zweiteseite.md
Content "/home/ralf/delme/hugo/meineseite/content/zweiteseite.md" created

Falls eure Website eine inhaltliche Hierarchie hat, könnt ihr auch so etwas machen:

hugo new schulungen/schulung-1.md

Für eure neue Inhaltsseite hat Hugo nur das Frontmatter (den Header) angelegt:

+++
date = '2025-07-25T23:11:56+02:00'
draft = true
title = 'Zweiteseite'
+++

Schreibt hier irgendetwas im Markdown-Format.

Den eigentlichen Inhalt müsst ihr im Markdown-Format hinzufügen. Hierbei kann man sich an den bestehenden Seiten im Content-Verzeichnis orientieren. Ich kopiere meistens eine bestehende Seite, anstatt mit Hugo eine neue Seite zu generieren. Da das Split-Theme weitere Inhaltsseiten nicht unterstützt, gibt es leider nichts zu sehen.

Medien

Jede Website verwendet Medien; seien es Bilder, Videos oder PDF-Dateien. Bei Hugo ist dafür das Unterverzeichnis static bestimmt. Dort könnt ihr euch nach Belieben (auch mit weiteren Unterverzeichnissen) einrichten. Beim Split-Theme sieht der Inhalt dieses Verzeichnisses so aus:

.
├── css
│   └── style.css
├── favicon.ico
├── images
│   ├── background.jpg
│   ├── background_orig.jpg
│   └── social_orig.jpg
└── videos
    └── background.mp4

Das Split-Theme speichert den Inhalt der Hauptseite in der Datei content/_index.md. Wenn ihr dort ein Bild einfügen möchtet, sieht das so aus:

+++
title = "Paulchen Bär"
tagline = "Von Beruf: Kuschelbär"
+++

Die Bären gleichen sich im Körperbau. Ihr Körper ist massig und stämmig, der Kopf groß, und die Gliedmaßen sind eher kurz und sehr kräftig. Die Augen sind klein, die Ohren rund und aufgerichtet.

![Bär](baer.jpg "Ein Bärenbild")

Die meist langgestreckte Schnauze beherbergt je nach Art 40 oder 42 Zähne. Die Füße enden in fünf Zehen, die mit nicht einziehbaren Krallen versehen sind.

Die Datei baer.jpg muss sich selbstverständlich im Verzeichnis static befinden.

Markdown-Erweiterungen

Wer bereits mit Markdown im Umfeld von Websites gearbeitet hat, weiss, dass man schnell an Grenzen stösst. Hugo bietet dafür einen Ausweg. Im Verzeichnis /layouts/shortcodes/ kann man spezielle HTML-Dateien anlegen, mit denen Markdown durch HTML-Schnipsel aufgepeppt werden kann. In den folgenden zwei Beispielen heissen diese Dateien pdflink.html und imgcenter.html:

Dieses Snippet kann in den Markdown-Text eingefügt werden, um eine PDF-Datei zu verlinken. Im Markdown sieht es dann so aus:

{{< pdflink src="/pdf/Flyer.pdf" title="Flyer">}}

Beim zweiten Beispiel soll ein Bild zentriert werden, was mit Markdown nicht möglich ist. Der Shortcode sieht so aus:

Eingebunden wird das mit:

{{< imgcenter src="/images/foto.png" width="398px" height="398px" >}}

Zu beachten ist, dass alle Parameter des HTML-Befehls mittels .Get vom Shortcode übergeben werden können. Als tag verwendet man den Namen (ohne Erweiterung) der Shortcode-Datei (im Beispiel: pdflink und imgcenter) Damit kann man sich beliebige HTML-Plugins für die Markdown-Seiten in Hugo erstellen.

Publizieren

Irgendwann hat man genügend entwickelt und lokal getestet. Dann möchte man die Website auf den Webserver kopieren. Mit Hugo geht das ganz einfach oder auch kompliziert, je nach Geschmack und Bedürfnis. In allen Fällen führt man den Befehl hugo aus:

Damit wird die vollständige Website im Unterverzeichnis public gebaut. Den Inhalt von public (nur das, nichts anderes) könnt ihr nun auf euren Webserver kopieren. Für alle, die public nicht via FTP auf den Webserver übertragen möchten, gibt es viele weitere Möglichkeiten (Stichwort: CD-CI). In dieser Serie verzichte ich darauf, das zu erklären.

Fazit

Mich verbindet eine Hassliebe mit Hugo. Einerseits fühle ich mich bei der Entwicklung einer Website frei, andererseits komme ich mir wie ein Urzeitmensch vor. Wer Hugo einsetzt, kommt schnell zum Ziel und braucht ewig, wenn es um Details geht. Im zweiten Teil dieser Hugo-Serie habe ich behauptet, dass der Befehl: grep -r Suchwort * euer bester Freund werden wird. Auch beim Schreiben dieses Artikels musste ich diesen Befehl anwenden. Wer errät, warum das so ist, gewinnt einen Gummipunkt.

Quelle: https://gohugo.io/ (Titelbild: ebenso)