Einführung: Eine statische Website mit Hugo generieren

Nachdem nun dieses Blog und die Microsite für meinen XMPP-Server auf statischen HTML-Dateien basieren, will ich eine Einführung in den Static Site Generator “Hugo” geben. Static Site Generatoren gibt es mittlerweile wie Sand am Meer. Einen Überblick kann man sich beispielsweise auf der Seite staticgen.com verschaffen. Hugo gefällt mir im Hinblick auf Geschwindigkeit und Einfachkeit allerdings am besten. Hervorzuheben ist außerdem die besonders einfache Installation: Zur Einrichtung wird einfach die passende Programmdatei als Executable heruntergeladen. Weitere Abhängigkeiten müssen nicht erfüllt werden.

Bevor es losgeht

… will ich kurz zusammenfassen, was Hugo ist und wie es funktioniert:

  • Inhalte für die Website werden in Markdown-Syntax oder in HTML lokal verfasst. Dazu wird ein beliebiger Text-Editor genutzt.
  • Das Design wird durch ein Theme bestimmt, welches Elemente aus der Go-Templatesprache verwendet.
  • Hugo wendet auf jede der verfassten Markdown- oder HTML-Seiten das Theme an und erzeugt fertige HTML Seiten. Daneben werden z.B. auch RSS-Feed, Sitemap und Übersichtsseiten automatisch generiert.
  • Die generierten HTML-Dateien können jetzt auf einem einfachen Webserver / Webspace veröffentlicht werden.

Download und Installation

Auf der GitHub Release-Seite des Projekts können die aktuellen Binaries heruntergeladen werden. Unter Linux wird die ausführbare Datei einfach in das benutzerdefinierte Programmverzeichnis geschoben, z.B.:

cd ~/Downloads
wget https://github.com/spf13/hugo/releases/download/v0.18.1/hugo_0.18.1_Linux-64bit.tar.gz
tar -xf hugo_0.18.1_Linux-64bit.tar.gz
sudo mv hugo_0.18.1_linux_amd64/hugo_0.18.1_linux_amd64 /usr/local/bin/hugo

Danach ist der Befehl “hugo” sofort im Terminal verfügbar.

Ein Hugo-Projekt erstellen

Im nächsten Schritt sucht ihr euch ein Verzeichnis, in dem ihr alle Projektdateien für ein Website-Projekt aufbewahren wollt. Navigiert dann im Terminal in dieses Verzeichnis und führt ein

hugo new site ./

aus. Dieser Befehl generiert den Grundstock für eure Microsite. Der Verzeichnisinhalt sollte nun in etwa so aussehen:

  • archetypes
  • config.toml (Grundkonfiguration der Site)
  • content (Enthält alle Seiten in Markdown- oder HTML-Format)
  • data
  • layouts
  • static (enthält statische Dateien und Verzeichnisse)
  • themes

Passt zunächst den Inhalt der Website-Konfiguration in config.toml an, z.B. so:

languageCode = "de-de"
title = "Meine Hugo-Site"
baseurl = "https://meinehugosite.tld"

Ein Theme herunterladen

Hugo kommt ohne Default-Theme. Würden jetzt Seiten erzeugt werden, würde man nichts als einen weißen Bildschirm sehen. Lasst uns als nächstes also ein Theme von https://themes.gohugo.io/ herunterladen und in das themes/ Verzeichnis kopieren. Das “Hemingway” Theme eignet sich hervorragend für einen kleinen Blog:

cd themes
git clone https://github.com/tanksuzuki/hemingway.git
cd ../

Nun muss das Theme noch in der Konfigurationsdatei config.toml als solches festgelegt werden:

languageCode = "de-de"
title = "Meine Hugo-Site"
baseurl = "https://meinehugosite.tld"
theme =	"hemingway"

Erste Inhalte erstellen

Nehmen wir an, die Site soll ein Blog sein, und ein neuer Blogpost soll erstellt werden. Mit dem Kommando

hugo new post/hallo-welt.md

wird eine neue Seite in Markdown-Format generiert. Diese liegt nun im Unterverzeichnis content/post/. Wenn ihr die Datei öffnet, sehr ihr, dass diese bereits folgendes beinhaltet:

+++
date = "2017-01-17T09:28:11+01:00"
title = "hallo welt"

+++

Dieser Kopfbereich - eingerahmt in “+++” enthält wichtige Metadaten für die jeweilige Seite / den jeweiligen Blogpost. In diesem Fall werden nur Seitentitel und Datum festgelegt. Allerdings können hier später auch Tags, Autor und beliebige weitere Metadaten zum Beitrag angegeben werden.

Der eigentliche Inhalt der Seite wird unter diesem Kopfbereich formuliert, z.B.

+++
date = "2017-01-17T09:28:11+01:00"
title = "Hallo Welt!"

+++

## Mein erster Beitrag
Dies ist mein erster Blogbeitrag im neuen **Hugo**-generierten Blog!

Ich empfehle euch, an dieser Stelle einen Blick auf das Markdown-Cheatsheet zu werfen. “##” leitet eine <h2>-Überschrift ein; “**” markiert einen Abschnitt fett.

Die Seite in der Live-Vorschau betrachten

Hugo verfügt über eine ausgeklügelte Live-Vorschau-Funktion. Ihr könnt den aktuellen Stand eurer Seite im Webbrowser betrachten, während ihr noch an den Inhalten (oder später evtl. am Theme) arbeitet. Bei jedem Abspeichern der bearbeiteten Datei aktualisiert Hugo die Vorschau im Webbrowser. Um die Vorschaufunktion zu starten, gebt folgenden Hugo-Befehlk ein:

hugo -D serve
Die -D Option sorgt dafür, dass auch als “draft” markierte Inhalte berücksichtigt werden. Ein Beitrag, der im Kopfbereich ein draft = true enthält, wird bei einem hugo später nicht veröffentlicht und wird auch bei einem einfachen hugo serve ignoriert, wenn die -D Flag fehlt.

Eure Site könnt ihr jetzt im Webbrowser unter der Adresse http://localhost:1313/ betrachten. Auf der Übersichtsseite sollte schon euer erster Blogpost zu sehen sein. Ihr könnt ihn öffnen, und den Inhalt des Posts im Texteditor ändern. Beim Speichern der Änderungen sollte die Seite im Browser automatisch aktualisiert werden. So kann man sehr bequem Inhalte formulieren und formatieren, und die Änderungen am Quellcode z.B. auf einem zweiten Monitor kontrollieren.

Der URL des neuen Posts entspricht übrigens dem Pfad, der beim “hugo new” Kommando angegeben wurde: /post/hallo-welt/ (ohne Dateiendung). Für jede Seite kann also invididuell bestimmt werden, unter welchem URL sie verfügbar sein soll.

Bilder und andere Dateien einbinden

Als Speicherort für alle Dateien, die abseits des Seitentextes verfügbar gemacht werden sollen, steht das “static” Verzeichnis zur Verfügung. Legt im “static” Verzeichnis ein neues Verzeichnis “images” an und speichert ein Bild Namens “test.jpg” darin.

Dieses Bild kann nun im Beitrag wie folgt eingebettet werden:

## Mein erster Beitrag
Dies ist mein erster Blogbeitrag im neuen **Hugo**-generierten Blog!

![Beispielbild-Beschreibung](/images/test.jpg)

Live-Ansicht

HTML-Seiten generieren und hochladen

Wenn die ersten Inhalte fertiggestellt sind, kann das Verzeichnis mit den statischen HTML-Dateien generiert werden, welches auf einen Webserver hochgeladen wird. Zum Generieren reicht ein

hugo

aus. Danach erscheint ein neuer Ordner “public” im Projekt-Wurzelverzeichnis. Der Inhalt dieses Verzeichnisses kann nun z.B. via rsync (SSH) oder FTP zum Webserver hochgeladen werden:

rsync -ave ssh public root@meinserver.tld:/var/www/

Das war’s für’s erste! In einem Folgebeitrag will ich euch erklären, wie ihr ein eigenes, einfaches Theme für eure Site erstellen könnt. Bis dahin könnt ihr noch ein wenig experimentieren oder euch die offizielle Hugo-Dokumentation ansehen.

Update: Der zweite Teil zum Thema “Eigenes Hugo Theme erstellen” ist jetzt online: https://thomas-leister.de/einfuehrung-in-hugo-theme-erstellen/