ubuntuusers.de

Hugo

Dieser Artikel wurde für die folgenden Ubuntu-Versionen getestet:


Du möchtest den Artikel für eine weitere Ubuntu-Version testen? Mitarbeit im Wiki ist immer willkommen! Dazu sind die Hinweise zum Testen von Artikeln zu beachten.

Hugo 🇬🇧 ist ein quelloffener statischer Webseiten-Generator für die Kommandozeile, basierend auf der Programmiersprache Go. Hugo ist unter Apache v2.0 lizensiert.

Dabei zeichnet er sich unter anderem durch Folgendes aus:

In diesem Artikel wird an die Benutzung von Hugo anhand der Erstellung einer simplen, Theme-basierten Webseite herangeführt.

Installation

Es stehen viele Möglichkeiten der Installation zur Verfügung, etwa über die Paketquellen, snap, manuell, via Docker und Homebrew. Siehe dazu die Installationsseite 🇬🇧 von Hugo.

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 

Benutzung

Nach der Installation kann Hugo im Terminal über den Befehl hugo gestartet werden. Dessen allgemeine Syntax lautet:

hugo [Optionen] | [Befehl] [Optionen] 

Ohne Optionen bzw. Befehle aufgerufen, prüft Hugo, ob es sich bei dem derzeitigen Verzeichnis um das Wurzelverzeichnis eines Hugo-Projektes handelt, und baut dann aus der Ordnerstruktur die statische Webseite.

Eine Übersicht über die wichtigsten Befehle und Optionen von Hugo findet sich in der folgenden Tabelle. Eine ausführlichere Darstellung ist der Kommandozeilen-Dokumentation 🇬🇧 zu entnehmen.

Wichtige Befehle und Optionen von Hugo
Befehl Optionen Beschreibung
hugo --cleanDestinationDir, --config DATEI, --watch, --destination VERZEICHNIS, --minify Baut die statische Webseite. Für die schnellere Auslieferung derselben können die Inhalte mittels --minify verkleinert werden.
hugo version - Gibt Versions- sowie Systeminformationen aus.
hugo completion bash|fish|zsh|powershell Generiert das Autokomplettierungs-Skript für die angegebene Shell.
hugo config --lang SPRACHKÜRZEL|mounts Gibt die Konfiguration für die vorliegende Seite aus, mit dem Befehl mounts für die eingehängten Dateien und Module.
hugo list all|drafts|expired|future Gibt alle Seiten, Entwürfe, abgelaufene, bzw. für die Zukunft datierte Veröffentlichungen aus, orientiert am jeweiligen front matter.
hugo new [content] -k DATEITYP, PFAD|site --format DATEIFORMAT|theme --format DATEIFORMAT Erstellt neuen Inhalt (Dateien) für die Seite, odr die Verzeichnisstruktur für eine neue Seite bzw. für ein neues Theme. Der Unterbefehl content wird für das Erstellen von mehrsprachigen Inhalten genutzt.
hugo server --tlsAuto, --tlsCertFile PFAD, --tlsKeyFile PFAD, --bind PORT|trust Baut die Seite (erbt daher alle Optionen von hugo), startet den Entwicklungsserver und serviert sie auf Port 127.0.0.1 bzw. einem angegebenen, inkl. Echtzeit-Neuladung. Mit trust wird die Hugo-CA auf dem System als vertrauenswürdig eingestuft.
hugo mod clean|get|graph|init|npm|tidy|vendor|verify Verwaltet die genutzten Module bzw. Abhängigkeiten, lokal oder global abgelegt, die jeweils einen oder mehrere Komponenten der Verzeichnisstruktur eines Hugo-Projektes bereitstellen. Für ausführliche Erläuterung siehe die Dokumentation 🇬🇧.

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.

Hinweis:

Seit Version 0.110.0 nutzt Hugo standardmäßig hugo.toml als Konfigurationsdatei. Der vorher genutzte Dateiname config.toml ist jedoch immer noch unterstützt.

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.

Archetypes anelegen

Eine Zeitersparnis für das Anelegen von neuen Inhalten bedeutet das Erstellen von Archetypes, d.h. Vorlagen, die beim Aufruf von hugo new content an die gewünschte Stelle kopiert werden.

Auch diese können mehrsprachig angelegt werden. Dazu legt man für jede Sprache im Ordner archetypes/ ein Verzeichnis an, in das man die Datei archetypes/default.md umbenannt zu post.md kopiert. Der Inhalt dieser Datei enthält bereits das sogenannte front matter 🇬🇧, in dem Metadaten der Seite stehen, also der Titel, das Datum sowie der Status als Entwurf. Erstere Informationen werden durch die mit geschweiften Klammern gekennzeichnete Template-Aktion automatisch beim Erstellen eines neuen Inhalts eingefüllt. Die Metadaten werden dann von den Layouts in das Aussehen der Seite eingepflegt. Mehr dazu weiter unten.

Das front matter des Archetypes unter archetypes/de/post.md kann nun folgendermaßen an das Format eines Bloposts angepasst werden, wobei die (automatisch erstellten) Taxonomien 🇬🇧 Tags und Kategorien mit einigen Standardwerten hinzugefügt werden, sowie der Name des Autors:

 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

Das Gleiche wird in einer Datei archetypes/en/post.md für die englische Sprache angepasst.

Für eine einfache Blog-Seite wie diese empfiehlt sich für den Ordner content folgende Struktur:

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

Die Datei _index.md bezeichnet den Inhalt der ersten Seite bzw. des Indexes einer Untereinheit der Seite – in diesem Fall also je Sprache den Inhalt der Hauptseite. die im Beispiel unter https://example.org/ angezeigt würde. Die Datei content/de/posts/first-post.md hingegen ließe sich in gebautem Zustand unter https://example.org/de/posts/first-post abrufen. Dementsprechend kann auch der Ordner content/de/posts/ eine solche Datei beinhalten. Ausführliche Dokumentation zur Organisation der Inhalte findet sich in der Projektdokumentation 🇬🇧.

Über folgende Befehle lassen sich die einzelnen Dateien nach den vorhandenen Layouts erstellen:

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 

Das nachherige Befüllen mit Inhalt soll hier dem Leser überlassen werden.

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

beispiel-hugo-seite.png
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 🇬🇧.

Schlusswort

Die Lektüre dieses Artikels hat zwar ein solides Verständnis der Funktionsweise von Hugo zufolge, jedoch wurde eigentlich nur an der Oberfläche gekratzt. Jetzt liegt es am geschätzten Leser, die eigene Seite den individuellen Bedürfnissen anzupassen. Auch das Schreiben von Modulen, sogar von vollwertigen Themes (nebst ihrer Anpassung) liegt theoretisch (eine gewisse Affinität mit der Webentwicklung vorausgesetzt) im Bereich des Möglichen! Dabei enthält Hugo auch spannende Entwicklerfunktionen, wie render hooks 🇬🇧, bereit.

Auch lohnt es sich wohl für den einen oder anderen, speziellere Funktionen der Inhalteverwaltung 🇬🇧, z.B. Syntaxhervorhebung, die Unterstützung für mathematische Gleichungen in LaTeX-Syntax oder auch Shortcodes 🇬🇧 kennen zu lernen, die den vielleicht anfänglich eng wirkenden Rahmen sprengen.

Diese Revision wurde am 11. September 2024 16:39 von karzer erstellt.
Die folgenden Schlagworte wurden dem Artikel zugewiesen: Programmierung, Go, Server, Webprogrammierung, Internet