Fertige Pakete¶

Auf der Releases-Seite des Hugo-Projektes werden fertige Binär- und Debian-Pakete zur sofortigen Installation angeboten. Folgende Befehlsfolge extrahiert das Archiv und installiert die Datei ausführbar im lokalen bin/-Verzeichnis:

wget https://github.com/gohugoio/hugo/releases/download/v<Version>/hugo_<Version>_linux-amd64.tar.gz
tar xvf hugo_0\.[[:digit:]]*\.[[:digit:]]_linux-amd64.tar.gz hugo
chmod u+x hugo && mv hugo ~/.local/bin/ 

Das aktuelle Debian-Paket lässt sich wie folgt herunterladen:

wget https://github.com/gohugoio/hugo/releases/download/v<Version>/hugo_<Version>_linux-amd64.deb 

Das Paket kann dann systemweit installiert ^[2] werden.

Über die Paketquellen¶

Hugo ist in den Ubuntu-Paketquellen enthalten und kann über folgendes Paket installiert werden:

• hugo (universe)

Befehl zum Installieren der Pakete:

sudo apt-get install hugo 

Oder mit apturl installieren, Link: apt://hugo

Snap-Paket¶

Hugo ist auch für den snap-Paketmanager paketiert:

sudo snap install hugo 

Autokomplettierung¶

Zuallererst sollte die automatische Komplettierung der Hugo-Befehle auf der Kommandozeile konfiguriert werden. Das Vorgehen wird hier beispielhaft an der Bash-Shell gezeigt.

hugo completion bash > hugo && sudo mv hugo /etc/bash_completion.d/ 

Die Shell muss anschließend neu gestartet werden. Bezüglich der Einrichtung für die anderen unterstützten Shells siehe die Dokumentation 🇬🇧.

Die neue Seite erstellen¶

Folgender Befehl legt die Ordnerstruktur für eine neue Hugo-Seite in einem Ordner ./neuu (Akronym für „Nachrichten eines Ubuntu-Users“) an:

hugo new site neuu 

Das Projektverzeichnis ist wie folgt strukturiert:

neuu/
├── archetypes
│   └── default.md
├── assets
├── content
├── data
├── hugo.toml
├── i18n
├── layouts
├── static
└── themes

Die Bedeutung der einzelnen Komponenten im Kontext der statischen Webseite wird im Folgenden erläutert. Weitere Einzelheiten können in der entsprechenden Dokumentation 🇬🇧 gefunden werden.

• archetypes: Dieses Verzeichnis enthält Templates, die Hugo bei der Erstellung neuer Inhalte für die Seite (hugo new) an die gewünschte Stelle kopiert. Das bereits angelegte Template default.md wird standardmäßig genutzt.

• assets: Hierin befinden sich Resourcen (z.B. JavaScript- und CSS-Dateien und auch Bilder), die via Pipes 🇬🇧 in den einzelnen Layouts eingebunden werden können.

• content: Die Dateien, die den eigentlichen Inhalt der Seite ausmachen, üblicherweise in Markdown verfasst. Dieses Verzeichnis kann in weitere zur Gruppierung der Inhalte unterteilt werden.

• data: Enthält Daten, die in Formaten wie JSON und YAML abgespeichert sind und etwa für auf der Seite enthaltene Statistiken und Auflistungen genutzt werden können.

• hugo.toml: Die Konfigurationsdatei von Hugo. Außer, wie vorgeschlagen, TOML, werden auch die Formate YAML und JSON unterstützt.

• i18n: Ablageort für die Übersetzungs-Tabellen einer mehrsprachigen Seite, die in den gleichen Formaten wie die Haupt-Konfigurationsdatei vorliegen können. Die Übersetzungen von Inhalten werden unter content/ erstellt, die Tabellen werden für statische Inhalte wie Menueinträge genutzt. Siehe die Einführung 🇬🇧.

• layouts: Die hier abgelegten HTML-Dateien oder Layouts bestimmen das Aussehen der Seite und setzen alle anderen Komponenten zu einem Gesamtbild zusammen. Die etwas komplexere Substruktur dieses Verzeichnisses wird weiter unten erläutert.

• static: Dateien, die beim Generieren der Seite in ihr Wurzelverzeichnis kopiert werden, wie etwa Icons. Hugo kann bei Bedarf auch für mehrere solche Verzeichnisse konfiguriert werden.

• themes: Enthält alle selbst erstellten oder heruntergeladenen Themes. Ein in einem solchen Theme definierte Layout kann durch ein an gleicher Stelle angelegtes überschrieben werden, bzw. zusätzlich angelegte Dateien erweitern die Funktionalität des Themes.

Die nachfolgend im Artikel aufgeführten Befehle müssen in dem Wurzelverzeichnis des Hugo-Projektes ausgeführt werden.

Anschließend wird empfohlen, in dem Projektverzeichnis ein Git-Repositorium anzulegen ^[7], um die Inhalte sinnvoll zu verwalten:

cd neuu/
git init 

Konfiguration¶

Dieser Schnipsel ist eine beispielhaft für eine zweisprachige Webseite angelegte Konfiguration, die in der Datei hugo.toml gespeichert wird. Anstelle dessen, um die Übersichtlichkeit zu erhöhen, können die einzelnen Bereiche auch in Dateien in einem Konfigurationsverzeichnis 🇬🇧 verteilt werden. Für eine ausführliche Einführung sollte die Referenz 🇬🇧 gelesen werden. Dort finden sich alle Hugo-spezifischen Konfigurationsparameter.

Das folgende Konfigurationsbeispiel ist stark auf das Theme zugeschnitten, das weiter unten installiert wird.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

baseURL = 'https://example.org/' # Nach diesem Wert generiert Hugo die absoluten URLs
title = 'Nachrichten und Erkenntnisse eines Ubuntu-Users'
# theme = 'mainroad' # Legt das Theme fest

[author]
  name = 'Arno Nymus'
  bio = 'Zum Imperator auf Lebenszeit auf dieser Seite akklamiert. Mehr über ihn [hier](/about). Dies könnte zu (s)einem erfolgreichen Blog werden.'

[params]
  copyright = 'Arno Nymus'
  post_meta = ['author', 'date', 'categories', 'translations']
  authorbox = true
  [params.widgets.social]
    email = 'augustus@example.org'
  [params.logo]
    subtitle = 'Cogito, ergo sum!'
  [params.sidebar]
    home = 'right'
    list = 'left' # Befindet sich auf einer Listen-Seite links, auf der Hauptseite rechts
    single = false
    widgets = ['recent', 'categories', 'taglist', 'social', 'languages']

# https://gohugo.io/content-management/multilingual/#create-language-specific-menu-entries
defaultContentLanguage = 'de' # Inhalte normalerweise in Deutsch
defaultContentLanguageInSubdir = true # Sprache über https://example.org/de aufrufbar
[languages]
  [languages.de]
    contentDir = 'content/de' # Inhalte in dieser Sprache werden im Verzeichnis content/de/ abgelegt.
    languageCode = 'de-DE'
    languageName = 'Deutsch'
    weight = 1 # Höchste Priorität bei Sortierung
    [languages.de.menus]
      [[languages.de.menus.main]]
        name = 'Hauptseite'
        pageRef = '/' # Pfad relativ zum Wurzelverzeichnis der Seite
        weight = 10
      [[languages.de.menus.main]]
        name = 'Nachrichtenticker'
        pageRef = '/posts'
        weight = 20
      [[languages.de.menus.main]]
        name = 'Über mich'
        pageRef = '/about'
        weight = 30
  [languages.en]
    contentDir = 'content/en-gb'
    languageCode = 'en-GB'
    languageName = 'English'
    title = 'News from an Ubuntu user' # Überschreibt den Seitennamen
    weight = 2
    [languages.en.params.logo]
      subtitle = 'Reference, Tutorials, and Explanations' # Überschreibt globalen Wert params.subtitle
    [languages.en.menus]
      [[languages.en.menus.main]]
        name = 'Home page'
        pageRef = '/'
        weight = 10
      [[languages.en.menus.main]]
        name = 'Posts'
        pageRef = '/posts'
        weight = 20
      [[languages.en.menus.main]]
        identifier = 'about'
        name = 'About'
        pageRef = '/about'
        weight = 30


# https://gohugo.io/content-management/taxonomies/
[taxonomies]
  category = 'categories' # Kategorien und Tags sind normalerweise aktiviert, müssen aber bei manueller Konfiguration erneut aufgeführt werden
  series = 'series'
  tag = 'tags' # Werte werden über front matter eines Artikels bestückt

Inhalte erstellen¶

Die eigentlichen Inhalte der Hugo-Seite werden im Verzeichnis content/ in Unterverzeichnissen dermaßen organisiert, dass sie die Struktur der fertig gebauten Seite widerspiegeln, und nachher in HTML konvertiert und anhand der Layouts in die Seite eingebettet. Standardmäßig handelt es sich dabei um Markdown-Dateien. Es werden auch die Markup-Sprachen RST, AsciiDoc, Org sowie Pandoc unterstützt 🇬🇧. Zur Anwahl muss die jeweilige Variante muss installiert sein und kann dann unter markdown.defaultMarkdownHandler in hugo.toml ausgewählt werden. In diesem Artikel wird mit Markdown und dem Standard-Renderer 🇬🇧 gearbeitet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

title: '{{ replace .File.ContentBaseName "-" " " | title }}' # Macht den normalisierten Dateinamen zum provisorischen Seitentitel
date: {{ .Date }}
draft: false  # Der Artikel wird beim Bauen der Seite berücksichtigt
params:
  author: Arno Nymus
categories:  # Taxonomie
- Persönlich
- Gedanken
- Geschäftlich
tags:  # Taxonomie
- Linux
- Go
- Ubuntu

content/
├── de
│   ├── about.md
│   ├── _index.md
│   └── posts
│       └── first-post.md
└── en
    ├── about.md
    ├── _index.md
    └── posts
        └── first-post.md

hugo new de/about.md && hugo new de/_index.md # kopiert archetypes/default.md
hugo new en/about.md && hugo new en/_index.md
hugo new content -k de/post content/de/posts/first-post.md # kopiert archetypes/de/post.md
hugo new content -k en/post content/en/posts/first-post.md # kopiert archetypes/en/post.md 

Templates¶

Templates sind HTML-Dateien mit Template-Aktionen 🇬🇧, die das Aussehen (Layout) der einzelnen Seiten einer Webseite definieren. Sie werden im layouts/-Verzeichnis des Hugo-Projektes bzw. demjenigen des Themes abgelegt. Diese Templates werden beim Ausführen von hugo gerendert. Die Aktionen können auf Werte in der Seitenkonfiguration (hugo.toml) oder im front matter einer Seite zurückgreifen (Methoden), dazu existieren etliche Funktionen 🇬🇧 um mit Inhalten zu arbeiten. Auch die grundlegende Funktionalität einer Programmiersprache, wie Schleifen, Bedingungen samt (Rechen-)Operatoren und das Setzen von Variablen sind unterstützt. Die Syntax der Template-Sprache ist an die der Programmiersprache Go angelehnt.

So lassen sich beispielsweise die Hauptseite (Home) oder eine beliebige Seite (Single) durch eigene Templates definieren. Durch eine besondere Dateistruktur kann man dies den individuellen Bedürfnissen anpassen, und beispielsweise auch ein besonderes Haupt- oder Einzelseiten-Template für eine bestimmte Gruppe von Seiten definieren. Neben den genannten Home- und Single-Templates sind noch solche für Seiten wichtig, die Unterseiten einer Gruppe auflisten (Section), und solche, die einer bestimmten Taxonomie zugeordnete Artikel zeigen (Taxonomy). Ein Basis-Template (Base) fügt das der Situation, d.h. der jeweiligen Seite angemessene Template mit weiteren Templates für Kopf und Fuß der Seite bzw. weitere Komponenten (partials) , die sich ebenfalls anpassen lassen, zum letztendlichen HTML-Dokument zusammen. Dieses wird dann als statische Seite ausgeliefert. Dieses Dokument 🇬🇧 gibt Aufschluss über die Reihenfolge, in der die Templates geladen werden, bzw. wo nach ihnen gesucht wird.

Die gesamte Liste der Template-Typen und ein Schaubild zur Dateistruktur findet sich in der Dokumentation 🇬🇧. Das Erstellen eines Beispiel-Layouts würde hier zu weit führen.

Themes¶

Ein Theme ist ein installierbares Modul 🇬🇧, das ein fertiges Layout sowie weitere Komponenten 🇬🇧 für einen bestimmten Typ von Webseite (z.B. Blog, Dokumentation) enthält.

Dabei macht man sich zunutze, dass ein Hugo-Projekt modular aufgebaut ist, d.h. beliebige Komponenten von dritter Seite oder einem selbst hinzugefügt werden können, die Funktionen in der Gesamtseite übernehmen. Dank der oben genannten Reihenfolge des Aussuchens, bestimmt das installierte Template das Verhalten der Seite genau dort, wo nicht an bevorzugter Stelle bereits Konfiguration besteht. Das bedeutet, man könnte bspw. ein Template themes/<theme-name>/layouts/partials/menu.html dadurch ersetzen, das man im Projektverzeichnis eine Datei layouts/partials/menu.html erstellt.

Die Seite https://themes.gohugo.io/ 🇬🇧 enthält eine Darstellung von durch die Community erstellten Themes. Ingesamt gibt es mittlerweile mehr als 500 Themes.

Zu Demonstrationszwecken wird das konventionelle Mainroad Blog-Theme 🇬🇧 im Folgenden installiert. Dazu muss zunächst das Repositorium desselben von GitHub mittels Git in dem Ordner themes/ als Submodul hinzugefügt (alternativ geklont) werden:

cd neuu/
git submodule add https://github.com/vimux/mainroad.git themes/mainroad 

Anschließend wird in der Konfiguration das Theme Hugo bekanntgemacht, dazu folgende Zeile in hugo.toml aktivieren:

1

theme = 'mainroad'

Statische Seite bauen¶

Beispielhafte Hugo-Seite

Nun kann die statische Seite erstmals gebaut werden. Dazu wird normalerweise einfach hugo ausgeführt, das die generierten Dateien in einem Ordner namens public/ ablegt. Dieses Verzeichnis kann dan von einem Webserver ausgeliefert werden. Hugo liefert außerdem einen Entwicklungs-Server mit, der es ermöglicht, über das Web-Interface auf die dort abgelegte Seite zuzugreifen. Außerdem führen Änderungen an den Projektdateien zu einem Neubau der entsprechneden statischen Dateien, sodass man diese direkt nachvollziehen kann. Man startet diesen Server über den folgenden Befehl:

hugo server -D 

Die Option -D (ein Alias für --cleanDestinationDir) entfernt den alten public/-Ordner.

Unter http://localhost:1313 kann die Seite dann getestet werden. Die Abbildung rechts zeigt eine mit der vorhanden Konfiguration und einigen Beispiel-Inhalten gebaute Seite.

Die Seite ausliefern¶

Nun, da die statische Seite besteht, ist der nächste Schritt, sie offen zugänglich zu machen (deployment), damit sich alle an der von Kompetenz zeugenden Aufmachung (und vielleicht nebenbei auch an den Inhalten) erfreuen können. Dazu kann ein traditioneller Webserver bespielt werden (etwa mittels rsync), gleichzeitig können selbstverständlich auch CDNs wie Cloudflare genutzt werden. Da die Hugo-Seite als Git-Repositorium angelegt ist ^[7], bietet sich auch Continuous Deployment als Option an, wobei die Seite direkt von Git-Hosting-Plattformen wie GitLab etwa über Netlify oder GitLab Pages generiert wird. Eine Übersicht der verschiedenen Optionen samt Anleitungen findet sich in der umfangreichen Hugo-Dokumentation 🇬🇧.