Hugo

Befehl Übersicht

Static Website Generator

Bei dynamischen Webseiten wird die Seite beim Aufruf am Server mittels PHP, ASP.NET … generiert. Statische Webseiten sind bereits beim Abruf fertig. Sie verwenden HTML für den Inhalt, CSS für das Styling und JavaScript für etwaige Scripts, die aber nur am Client bzw. Webbrowser laufen. Statische Webseiten Generatoren generieren aus Projektdateien, bestehend aus Content-Dateien und Layout-Dateien, die statische Website. Somit kann nach einmaliger Einrichtung am Inhalt gearbeitet werden, ohne sich wieder um die Gestalltung kümmern zu müssen. Der Inhalt ist von der Gestaltung unabhängig, was wiederum bei einer Änderung der Gestalltung keine Rückwirkung auf den Inhalt hat.

Hugo ist ein Open-Source Static Website Generator geschrieben in Go. Er generiert HTML Seiten aus in markdown beschriebenen Inhalten. Ein großer Vorteil von Hugo ist die Geschwindigkeit beim Generieren der Seiten. Somit können Änderungen am Inhalt sofort betrachtet werden.

Vorbereitungen

Zuerst muss Hugo installiert werden (https://gohugo.io/installation/). Unter Windows reicht es die aktuelle Hugo Version (https://github.com/gohugoio/hugo/releases) herrunter zu laden und in einen Ordner zu kopieren (z.B. “C:\hugo"). Danach muss dieser Programm-Pfad in die Umgebungsvariable PATH eintragen werden. Einen Test kann man mittels hugo help oder hugo version vornehmen.

Ausgabe:

1hugo v0.143.1-0270364a347b2ece97e0321782b21904db515ecc+extended+withdeploy windows/amd64 BuildDate=2025-02-04T08:57:38Z VendorInfo=gohugoio

Für das Bearbeiten der Konfigurations- und Markdown-Dateien kann man VSCode verwenden. VSCode kann als Installationsdatei heruntergeladen und einfach installiert werden.

Website Erstellen und Öffnen

Eine Hugo Projektstruktur kann mit hugo new site test-webseite angelegt werden (yaml anstatt toml Konfigurationsdatei: hugo new site test-website --format yaml).

Ausgabe:

 1Congratulations! Your new Hugo site was created in C:\Users\asdf\Desktop\website\test-webseite.
 2
 3Just a few more steps...
 4
 51. Change the current directory to C:\Users\asdf\Desktop\website\test-webseite.
 62. Create or install a theme:
 7   - Create a new theme with the command "hugo new theme <THEMENAME>"
 8   - Or, install a theme from https://themes.gohugo.io/
 93. Edit hugo.toml, setting the "theme" property to the theme name.
104. Create new content with the command "hugo new content <SECTIONNAME>\<FILENAME>.<FORMAT>".
115. Start the embedded web server with the command "hugo server --buildDrafts".
12
13See documentation at https://gohugo.io/.

Danach kann das Projekt mit VSCode geöffnet werden code . (im Ordner “test-webseite”). In Windows kann man auf dem Projektordner Rechtsclicken und mit “VSCode” öffnen. Die Ordner Struktur ist wiefolgt:

• archetypes/
  • default.md
• assets/
• content/
• data/
• i18n/
• layouts/
• public/
• static/
• themes/
• hugo.toml

Archetypes

Die Dateien in diesem Ordner dienen als Vorlagen für die Inhaltsdateien die mit “hugo new” angelegt werden. Für verschiedene Inhaltstypen können eigene Vorlagen angelegt werden (post/tutorials/arcticles/…). Zu Begin gibt es eine Default-Vorlage (default.md). Beim Erstellen einer neuen Datei, z.B. eines neuen Posts (z.B. “hugo new posts/erster-post.md”) wird die markdown Datei bereits vorausgefüllt. Ist eine “posts.md” Datei vorhanden, so wird diese verwendet. Andernfalls wird die “default.md” Datei verwendet.

Assets

Dieser Ordner beinhaltet statischen Inhalt wie Stylesheets, Scripts oder Bilder (z.B. Fav-Icon, Wasserzeichen …). Die Dateien werden beim Erstellen der Website mitverarbeitet und in den “public” Ordner kopiert. Diese Inhalte können unabhängig vom restlichen Inhalt und von Vorlagen organisiert werden. Das macht es einfacher diese statischen Inhalte zu Verwalten oder sie zu Aktualisieren.

Config

Die “hugo.toml” Datei ist eine Konfigurationsdatei für die Hugo Website. Sie kann direkt im Projekt-Wurzelverzeichnis abgelegt werden oder unter “config/_default/hugo.toml”. Anstelle einer Konfigurationsdatei kann der “config/_default” Ordner auch mehrere Konfigurationsdateien beinhalten. Die Konfigurationsdateien beinhalten die Einstellungen und Optionen, womit das Verhalten der Website definiert wird. Beispiel Konfigurationswerte sind Titel, Base URL, Theme, Menü, … (Übersicht der Variablen). Eine sehr interessante Option ist, dass man hugo mitteilen kann, welche Dateien und Ordner beim Verarbeiten ignoriert werden sollen ignoreFiles = ['TODO', 'OLD', 'IGNORE']. Somit werden sämtliche Dateien oder Verzeichnisse mit einem der aufgelisteten Wörter ignoriert und auch nicht in den “public” Ordner übernommen.

Content

In diesem Ordner werden alle Markdown Dateien inklusive Bilder und Mutlimedia Dateien abgelegt. Der Ordner beinhaltet den tatsächlichen Website Inhalt (Posts, Seiten, …). Hugo verarbeitet diese Dateien und generiert damit die HTML Dateien. Mit Hilfe von Ordnern können die Inhalte in Bereiche/Sektionen eingeteilt werden (z.B.: /post für Blog-Posts, /tutorials für Tutorials, /articles für Artikel …). Mit dem Ordner-Namen wird nach einer passenden Vorlage im “Archetypes” Ordner gesucht.

Data

Dieser Ordner beinhalted Daten welche zum Generieren der Website verwendet werden können. Sie werden in Konfigurationsdateien abgelegt (YAML, JSON oder TOML). Sie umfassen z.B. Seiten Konfigurationen, Angaben zum Author usw. Diese Daten können in den Vorlagen benützt und referenziert werden.

I18n

Wird die Website in mehreren Sprachen engeboten, so beinhaltet dieser Ordner die Übersetzungstabellen.

Layouts

Hier werden die HTML Vorlagen abgelegt, welche für die Gestaltung der Website verwendet werden. Diese Vorlagen werden beim Generieren der HTML Dateien für die Gestaltung jeder einzelnen Seite verwendet. Beim Verwenden von Themes müssen die Dateien oft nicht angelgt werden, es wird nur das Theme angepasst. Der Ordner kann Vorlagen für Listen-Seiten (list pages)(Liste der Posts …), für die Start-Seite (homepage), für die einzelnen Seiten (single page), … beinhalten.

Public

In diesem Ordner werden die generierten statischen Website Dateien abgelegt. Er beinhaltet HTML, CSS, JavaScript, Bilder … Ausgabedateien. Wird die Website mit “hugo server” generiert, so verwendet hugo lokale Pfadangaben. Diese Ausgabe ist nicht für den Upload zum Server gedacht. Wird die Website mit “hugo” erstellt, so wird die “baseURL” herangezogen. Diese Ausgabe kann direkt auf den Server hochgeladen werden.

Resources

Dieser Ordner beinhaltet generierte Dateien die zwischengespeichert werden. Zum Beispiel werden bei der Verwendung von Bildverarbeitung die Bilder hier verarbeitet.

Static

Der Static Ordner beinhaltet statische Dateien die von Hugo nicht weiter verarbeitet werden. Diese Dateien werden direkt übernommen, ohne dass Hugo sie verarbeitet oder verändert. Diese Dateien können einfach referenziert werden “{{.Site.BaseURL }}/images/logo.png}}”. In diesem Ordner können statische Bilder (ohne Weiterverarbeitung durch Hugo) oder Downloads verwaltet werden. Ein Beispiel ist die Ablage der Google-Authentifizierungsdatei welche direkt im Ausgabeordner gelangen soll.

Themes

Hier können eigene oder bereits vorbereitete Themes abgelegt werden. Diese werden für die Gestaltung der Website verwendet. In dem Ordner können auch mehrere Themes abgelegt werden. Das verwendete Theme wird in der Konfigurationsdatei definiert. Somit kann die Gestaltung einfach gewechselt werden, ohne den Inhalt zu modifizieren.

Theme Verwenden

Für Hugo gibt es sehr viele unterschiedliche Themes. Ein Theme wird installiert, indem man die Dateien in dem Themes Ordner kopiert oder mit Git verwendet.

Git Clon:

1git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1
2cd themes/PaperMod
3git pull

Git Submodul:

1git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
2git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically)

Für meine Website interessante Themes:

• PaperMod
• blowfish
• beautifulhugo
• lotusdocs

Nach dem Installieren des Themes kann man es in der Hugo Konfigurationsdatei aktivieren. Die anderen verfügbaren Einstellungen kann man auch gleich anpassen.

1baseURL = 'https://werner.dichler.at/'
2languageCode = 'de-DE'
3title = 'WeDi'
4theme = 'beautifulhugo'

Erste Seite Erstellen

Die Index-Seite (Homepage) der Website kann man mit hugo new _index.md erstellen. Der Inhalt dieser Datei ist in Markdown verfasst und beinhaltet zu Begin den “Front Matter” Bereich. Weitere Markdown Zusammenfassungen findet man im Markdown Guide oder Markdown Cheatsheet.

 1+++
 2date = '2025-02-23T11:31:24+01:00'
 3draft = false
 4title = 'WeDi'
 5+++
 6
 7# Überschrift 1
 8Etwas Text um die Darstellung zu testen.
 9
10## Überschrift 2
11
12Weiterer Test Text.
13Weiterer Test Text. Weiterer Test Text.

Lokalen Server Starten

Die Hugo Website kann lokal getestet werden indem man den in Hugo integrierten Server startet hugo server. Der Server liefert die Website unter “http://localhost:1313/” aus. Er überprüft im Hintergrund ob sich die Dateien ändern und aktualisiert gegebenenfalls sofort die Website Darstellung.

 1hugo serve
 2Watching for changes in C:\Users\werne\Desktop\website\wedi\{archetypes,assets,content,data,i18n,layouts,static,themes}
 3Watching for config changes in C:\Users\werne\Desktop\website\wedi\hugo.toml
 4Start building sites …
 5hugo v0.143.1-0270364a347b2ece97e0321782b21904db515ecc+extended+withdeploy windows/amd64 BuildDate=2025-02-04T08:57:38Z VendorInfo=gohugoio
 6
 7                   | EN   
 8-------------------+------
 9  Pages            |  10
10  Paginator pages  |   0
11  Non-page files   |   0
12  Static files     | 184
13  Processed images |   0
14  Aliases          |   2
15  Cleaned          |   0
16
17Built in 123 ms
18Environment: "development"
19Serving pages from disk
20Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
21Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
22Press Ctrl+C to stop

Finale Website Generieren

Um die Hugo Website für den Server Upload zu generieren (es werden zum Teil andere URLs verwendet) gibt man einfach hugo ein. Anschließend kann man sämtliche Dateien unter “public" auf den Server laden.

1hugo
2Start building sites … 
3hugo v0.143.1-0270364a347b2ece97e0321782b21904db515ecc+extended+withdeploy windows/amd64 BuildDate=2025-02-04T08:57:38Z VendorInfo=gohugoio

Hugo Markdown Beispiele

Links / Referenzen

Interne absolute Links (z.B.: http://asdf.com/about/):

1{{< ref "document.md" >}}
2{{< ref "#anchor" >}}
3{{< ref "document.md#anchor" >}}

Interne relative Links (z.B.: /about/):

1{{< relref "document.md" >}}
2{{< relref "#anchor" >}}
3{{< relref "document.md#anchor" >}}

Externe Links:

 1<https://www.muster.org>
 2<max@muster.com>
 3[Link Text](https://muster.com)
 4[Link Text](https://muster.com "Hover Text")
 5
 6Nicht verwendet werden sollte folgendes:
 7[Link Text](https://muster.com/seite 1.html)
 8
 9Leerzeichen werden von Markdown nicht erkannt.
10[Link Text](https://muster.com/seite%201.html)

Bilder Einfügen

Statische Bilder können z.B. unter “static/images/” abgelegt werden und per markdown einfach eingebettet werden. Werden Bilder noch weiterverarbeitet (z.B. für eine Gallerie …), so speichert man sie am besten mit den Seiten im “content” Ordner.

1Angabe mit Absolut-Pfad bezogen auf Base-URL:
2![Alternativ-Text](/images/test.jpg)
3
4Angabe mit Relativem Pfad bezogen auf Inhalt-Datei:
5![Alternativ-Text](../images/test.jpg)
6![Alternativ-Text](/images/test.jpg "Bildbeschreibung")
7
8Bild mit Link:
9[![Alternativ-Text](/images/test.jpg "Bildbeschreibung")](https://muster.com)

Code Highlighting

Hugo verwendet für Code-Highlighting Chroma. Details findet man unter anderem hier.

1Interessanter Text mit ``inline code``.
2
3{{< highlight cpp "linenos=inline" >}}
4// ... code
5{{< / highlight >}}

Besonderheiten

Möchte man nur eine neue Zeile ohne einen neuen Absatz, so muss man die vorhergehende Zeile mit zwei Leerzeichen beenden. Damit Hugo mehrere Leerzeilen nicht wegoptimiert und als solche behält kann man Leerzeichen einfügen.

1   add single space
2   add two spaces
3   add four spaces

Hugo parst selbst die Texte, welche als Code markiert sind. Somit ist es schwierig Hugo Code darzustellen. Um das Parsen zu verhindern kann man eine spezielle Zeichenfolge verwenden

1{{</* highlight cpp "linenos=inline" */>}}
2// ... code
3{{</* / highlight */>}}

Anpassung von Themes

Für viele Themes gibt es eine gute Dokumentation mit Start-Anleitungen, z.B. für blowfish. Hier wird z.B. beschrieben, dass die von hugo erstellte Konfigurationsdatei im Projekt-Wurzelverzeichnis gelöscht werden kann und die Konfigurationsdateien von blowfish “themes/blowfish/config/_default” kopiert werden sollen “config/_default”. Diese Dateien werden im Anschluss zum Konfigurieren von der Website und von blowfish verwendet.
Sämtliche andere Änderungen an blowfish macht man, indem man die Original-Datei kopiert und an “gleicher” Stelle im Projekt einfügt (ohne “themes/blowfish” davor). Hugo verwendet beim Erstellen der Seite nur noch die Kopie.

Lokale Versionierung mit Git

Damit Änderungen der Website nachverfolgt werden können und mögliche Verschlechterungen zurückgenommen werden können, verwendet man Versionierung mit Git oder SVN Repositories. Versionierung kann auch Helfen damit man nur die geänderten Dateien im “puglic” Ordner auf den Server hochladen kann.
Die Versionierung startet mit dem Installieren von Git. Danach kann das Git-Kommandozeilenfenster im Projekt-Ordner geöffnet werden (Erweiterung im Rechts-Klick Menü). Damit nachfolgende Commits einem Benutzer zugeordnet werden können, kann man den Benutzer global definieren git config --global user.email "max.muster@mail.com. Danach kann im aktuellen Verzeichnis ein lokales Git Repository angelegt werden git init. Damit Git auch die selben Dateien und Verzeichnisse wie hugo ignoriert, kann man eine “.gitignore” Datei anlegen.

*TODO*
*OLD*
*IGNORE*

Danach kann man sämtliche Dateien und Verzeichnisse mit git add . hinzufügen und den ersten Commit speichern git commit -m 'message'. Nachfolgend kann man sich den Repository Status mit git status anzeigen lassen und Änderungen verfolgen.

Eine gute Git Kommando-Übersicht findet man in der Git Dokumentation oder in einem Git Cheat Sheet. Eine Übersicht über die Möglichkeiten in .gitignore findet man in einem .gitignore Tutorial.

Weiterführende hugo Links

https://hygraph.com/blog/hugo-static-site https://linz.coderdojo.net/uebungsanleitungen/programmieren/web/erste-schritte-mit-hugo/

https://discourse.gohugo.io/t/storing-image-as-asset-or-page-resource/31692/3 https://discourse.gohugo.io/t/best-practices-assets-with-content/9984/2

https://privat.albicker.org/blog/2017-02-03-hugo-die-plage-mit-den-urls.html