Hugo


statische Webseiten mit „Hugo“ generieren

Angeregt durch einen Artikel in der aktuellen LinuxUser 04.2021 möchte ich hier eine einfache Möglichkeit vorstellen, optisch ansprechende statische Webseiten mit Hilfe von Markdown und dem statischen Website-Generator Hugo zu erstellen. Diese kleine Anleitung soll dabei selbst als Beispiel dienen.

erste Schritte

Die folgende Anleitung beschreibt die Installation am Beispiel eines 64-Bit Linux-Systems. Für andere Betriebssysteme bzw. Architekturen muss die Installation entsprechend angepasst werden. Hugo steht für Linux, Windows, macOS, OpenBSD und FreeBSD als ausführbares Programm zur Verfügung. Außerdem lässt es sich auf weiteren Systemen compilieren. Details siehe https://gohugo.io/getting-started/installing.

Installation

Sie benötigen die eigentliche Software und eine geeignete Vorlage für ihr Webprojekt.

Software

Unter Linux überprüfe man zunächst, ob Hugo in den Repositories der entsprechenden Distribution enthalten ist. Falls das nicht der Fall ist, installiert man das zur Architektur passende Binary von folgender Webseite: https://github.com/gohugoio/hugo/releases.

In meinem Fall ist das die Datei hugo_extended_0.81.0_linux-64bit.tar.gz. Soweit vorhanden sollte man die Version mit extended im Namen bevorzugen. Einige Layouts benötigen diese Programmvariante. Nach dem Download entpackt man das Archiv (tar xvzf hugo_extended_0.81.0_linux-64bit.tar.gz) und kopiert das hugo-Binary an eine geeignete Stelle (z. B. als root nach /usr/local/bin für alle Benutzer oder als normaler User nach ~/bin).

Vorlagen (Themes)

Themen für das Webseiten-Layout finden sie unter https://themes.gohugo.io/. Die Vorlagen sind in der Regel als ZIP-Archive verfügbar. Für die kostenfreie Verwendung sollten sie auf die Lizenzen der ausgewählten Vorlage achten.

Neues Projekt anlegen

Wechseln sie in das Verzeichnis, in dem sie ihre Webprojekte erstellen wollen. Erstellen sie jetzt einen neuen Projektordner mit dem Befehl hugo new site PROJEKTNAME. In meinem Beispiel lautet der Befehl hugo new site Anleitungen. Dabei wird ein Ordner Anleitungen mit folgendem Inhalt erzeugt:

Ordner

Alle weiteren Hugo-Kommandos müssen jetzt aus dem erzeugten Projektordner heraus ausgeführt werden! In meinem Beispiel also aus /home/wilke/Homepage/Hugo/Anleitungen.

In den Ordner themes entpacken sie jetzt das ZIP-Archiv mit dem heruntergeladenen Thema. Es empfiehlt sich, den Namen des Themenordners etwas einzukürzen. In meinem Beispiel enthält das verwendete Thema Mainroad-master.zip den Ordner Mainroad-master, den ich auf mainroad verkürzt habe. Das Thema Mainroad steht unter der Lizenz GPLv2 (siehe https://github.com/vimux/mainroad/blob/master/LICENSE.md).

Jetzt sollte man die Datei config.toml bearbeiten. Für diese Seite habe ich sie wie folgt abgeändert:

baseURL = "http://www.wilke-j.de/Anleitungen/"
languageCode = "de-DE"
title = "Anleitungen"
theme = "mainroad"
enableRobotsTXT = true

Damit sind die vorbereitenden Arbeiten bereits abgeschlossen.

neue Seiten anlegen

Im zunächst noch leeren Ordner content kann man nun seine Markdown-Dateien speichern. Eine neue Markdown-Datei erzeugt man mit dem Befehl hugo new PFAD/DATEINAME. Im Falle dieser Seite ist das die Datei Hugo.md (also: hugo new Hugo.md). Die Datei kann aber auch mit einem beliebigen Markdown-Editor erzeugt werden.

Damit Hugo Menüs erstellen kann und das Layout dem Typ der Seite entsprechend ausgewählt werden kann, muss die Markdown-Datei einen Vorspann im YAML-Format bekommen. Mit Hugo erzeugte Dateien haben diesen Vorspann bereits. Er muss aber noch angepasst werden. Das sieht in meinem Beispiel so aus:

---
title: "Hugo"
author: "J. Wilke"
date: 2021-03-13
type: page
menu: main
---

Die Angabe title beschriftet den Menüeintrag auf der fertigen Webseite. Die Angabe type gibt an, nach welcher Vorlage die Eingabedatei formatiert werden soll. Je nach Thema sind verschiedene Typen verfügbar. Der Eintrag menu: main sorgt dafür, dass auf der Hauptseite ein Menüeintrag angelegt wird. Die anderen Angaben werden je nach Thema ausgelesen und evtl. an bestimmten Stellen der Webseite eingefügt.

Jetzt wird der Inhalt der Seite geschrieben. Zur sehr leicht zu erlernenden Markdown-Syntax möchte ich hier nichts sagen. Im Internet finden sich genügend Anleitungen.

Webseite erzeugen und anschauen

Das Erzeugen der Webseite geht sehr schnell und erfordert nur den Befehl hugo aus dem Projektverzeichnis heraus. In diesem Beispiel zeigt das Terminal:

Terminal

Die erzeugte Webseite wird im Ordner public gespeichert. Um sie sich im Browser ansehen zu können, startet man mit dem Befehl hugo server einen Webserver. Im Browser lässt sich die erzeugte Seite nun mit http://localhost:1313/Anleitungen anzeigen. Der Pfad /Anleitungen im Beispiel ist notwendig, da die Datei config.toml bei baseURL diesen Pfad hinter der Webadresse enthält.

Falls der Aufruf mit localhost nicht funktioniert, kann man auch die IP-Adresse des Hosts (normalerweise 127.0.0.1) verwenden.

Solange der Webserver läuft werden Änderungen an der Markdown-Quelldatei im Webbrowser angezeigt. Die Ausgabedateien werden aber erst nach einem erneuten Aufruf von hugo angepasst.

Die Tastenkombination <STRG><C> beendet den Webserver.

Wenn alles wie gewünscht funktioniert kann man nun die erzeugte Webseite im Verzeichnis public auf den Webserver hochladen.

Bilder einfügen

Bilddateien gehören in den Ordner static. Sie werden unverändert in das Wurzelverzeichnis der Webseite kopiert. Wird die erzeugte HTML-Datei wie im Beispiel in einem Unterordner (hugo) gespeichert, dann muss der Pfad des verlinkten Bildes auf das Elternverzeichnis verweisen. Die erste Abbildung namens Ordner.png in diesem Beispiel wurde also mit folgendem Markdown-Code eingefügt:

![Ordner](../Ordner.png)

zum Abschluss …

… noch zwei Bemerkungen zu Markdown:

  • Markdown erlaubt auch die Verwendung von HTML-Sprachelementen. Fügt man z. B. den Code einer HTML-Entität wie &rarr; in den Markdown-Quelltext ein, entsteht daraus ein Pfeil (→). Das gleiche gilt auch für HTML-Tags. So kann man z. B. statt mit **Fetter Text** auch mit <b>Fetter Text</b> formatieren.
  • Es gibt eine ganze Reihe von Markdown-Editoren, mit denen man die Markdown-Quelltexte bequem schreiben kann. Ich benutze für dieses Beispiel den Editor Typora (https://typora.io/).