↓ Zum Hauptinhalt springen
Patrick Adams
  1. Anleitungen/

Hugo installieren: Statische Webseiten in Sekunden bauen

5 min·
Hugo Webseite Static-Site Blowfish
Patrick Adams
Autor
Patrick Adams
Linux-Administrator und IT-Specialist. Ich schreibe über Server, Self-Hosting und Open-Source-Software, praxisnah und selbst getestet. Mehr über mich →
Inhaltsverzeichnis
Hugo baut aus einfachen Markdown-Dateien eine komplette Webseite, ohne Datenbank, ohne PHP und ohne Sicherheitslücken in Plugins. Das Ergebnis sind reine HTML-Dateien, die du auf jeden Webserver legen kannst. Genau so entsteht auch diese Seite. Hier installierst du Hugo und legst deine erste Seite mit dem Theme Blowfish an.
Voraussetzungen: ein Rechner mit Linux, Windows oder macOS und Grundkenntnisse im Terminal. Zusätzlich brauchst du Git, um Themes einzubinden. Eine Programmiersprache musst du nicht beherrschen.

Warum Hugo?
#

  • Schnell: Hugo baut auch Seiten mit Hunderten Beiträgen in wenigen Sekunden.
  • Sicher: Auf dem Server liegen nur statische Dateien. Es gibt keinen Login und keine Datenbank, die angegriffen werden kann.
  • Günstig: Ein einfacher Webspace reicht, ganz ohne PHP oder Datenbank.
  • Versionierbar: Alle Inhalte sind Textdateien und lassen sich mit Git verwalten.

Hugo installieren
#

Hugo gibt es in zwei Varianten: Standard und Extended. Viele Themes wie Blowfish brauchen die Extended-Version, weil sie damit Stylesheets verarbeiten. Installiere deshalb immer Hugo Extended.

Die Pakete in den Debian- und Ubuntu-Quellen sind oft stark veraltet. Hol dir stattdessen das aktuelle Paket direkt von GitHub. Diese Befehle ermitteln die neueste Version automatisch:

sudo apt update && sudo apt install -y git curl wget
VERSION=$(curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest | grep -m1 '"tag_name"' | cut -d '"' -f4 | sed 's/^v//')
wget "https://github.com/gohugoio/hugo/releases/download/v${VERSION}/hugo_extended_${VERSION}_linux-amd64.deb"
sudo apt install -y "./hugo_extended_${VERSION}_linux-amd64.deb"
rm "hugo_extended_${VERSION}_linux-amd64.deb"

Auf einem Raspberry Pi oder anderen ARM-Rechnern ersetzt du amd64 durch arm64.

Öffne die PowerShell und installiere Hugo Extended und Git mit winget:

winget install Hugo.Hugo.Extended
winget install Git.Git

Schließe die PowerShell danach und öffne sie neu, damit die Befehle gefunden werden.

Arbeitest du lieber unter Linux, kannst du Hugo auch in WSL mit Ubuntu installieren und dort der Anleitung für Debian und Ubuntu folgen.

Mit Homebrew geht es in einer Zeile. Das Paket enthält bereits die Extended-Version:

brew install hugo git

Prüfe danach, ob alles geklappt hat:

hugo version

In der Ausgabe muss extended stehen, zum Beispiel:

hugo v0.169.0-...+extended linux/amd64 BuildDate=...

Die erste Seite anlegen
#

Lege ein neues Projekt an und mach den Ordner direkt zu einem Git-Repository:

hugo new site meine-seite
cd meine-seite
git init

Hugo erstellt dabei diese Struktur:

OrdnerInhalt
content/deine Beiträge und Seiten als Markdown
assets/Bilder, CSS und JavaScript, die Hugo verarbeitet
static/Dateien, die unverändert übernommen werden, etwa Favicons
layouts/eigene Vorlagen, die das Theme überschreiben
themes/installierte Themes
hugo.tomldie Konfiguration der Seite

Theme installieren: Blowfish
#

Ohne Theme zeigt Hugo nur eine leere Seite. Ich nutze Blowfish, ein modernes Theme mit Dark Mode, Suche, Diagrammen und vielen fertigen Bausteinen. Am saubersten bindest du es als Git-Submodul ein. So bleibt das Theme getrennt von deinen Inhalten und lässt sich später mit einem Befehl aktualisieren:

git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

Blowfish arbeitet mit mehreren Konfigurationsdateien statt einer einzigen. Kopiere die Vorlagen des Themes in dein Projekt und lösche die alte Datei:

mkdir -p config/_default
cp themes/blowfish/config/_default/*.toml config/_default/
rm hugo.toml

Öffne jetzt config/_default/hugo.toml und passe die wichtigsten Zeilen an:

theme = "blowfish"
baseURL = "https://www.deine-domain.de/"
defaultContentLanguage = "de"

Achte darauf, dass vor theme keine Raute steht und die baseURL mit einem Schrägstrich endet.

Ändere niemals Dateien direkt im Ordner themes/blowfish. Bei einem Update werden sie überschrieben. Willst du etwas anpassen, legst du eine Datei mit demselben Pfad in deinem eigenen layouts/- oder assets/-Ordner an. Die hat dann Vorrang vor der Version des Themes.

Den ersten Beitrag schreiben
#

Mit diesem Befehl legt Hugo einen neuen Beitrag mit fertigem Kopfbereich an:

hugo new content posts/mein-erster-beitrag.md

Öffne die Datei und ergänze Text unter dem Kopfbereich:

---
title: "Mein erster Beitrag"
date: 2026-11-03
draft: true
---

Hallo Welt! Das ist mein erster Beitrag mit **Hugo**.

Solange draft: true gesetzt ist, gilt der Beitrag als Entwurf und wird nicht veröffentlicht. Setzt du den Wert auf false, erscheint er auf der fertigen Seite.

Die Seite lokal ansehen
#

Hugo bringt einen eigenen Testserver mit. Die Option -D zeigt auch Entwürfe an:

hugo server -D

Öffne http://localhost:1313 im Browser. Jede Änderung an einer Datei erscheint sofort, ohne dass du neu laden musst. Mit Strg+C beendest du den Server.

Hängt die Vorschau oder siehst du alte Inhalte, hilft ein sauberer Neustart:

rm -rf public resources && hugo server -D --disableFastRender

Die Seite bauen und veröffentlichen
#

Für die echte Webseite baust du die Seite ohne Entwürfe und mit verkleinerten Dateien:

rm -rf public resources
hugo --gc --minify

Das Ergebnis liegt im Ordner public/. Diesen Inhalt lädst du in das Webverzeichnis deines Servers, zum Beispiel per SFTP oder bequemer mit rsync:

rsync -avz --delete --exclude='.well-known' public/ benutzer@server:/pfad/zum/webverzeichnis/
Lade niemals den public-Ordner hoch, den der Testserver hugo server erzeugt hat. Der enthält Entwürfe und Links auf localhost. Baue vor dem Hochladen immer mit hugo --gc --minify neu.

Ins Git-Repository gehören die Ordner public/ und resources/ übrigens nicht, sie werden ja bei jedem Bauen neu erzeugt:

printf "public/\nresources/\n.hugo_build.lock\n" > .gitignore

Hugo und Blowfish aktualisieren
#

Hugo aktualisierst du, indem du die Installation einfach mit der neuen Version wiederholst. Unter Debian und Ubuntu laufen dazu die Befehle von oben erneut durch, unter Windows winget upgrade Hugo.Hugo.Extended und unter macOS brew upgrade hugo.

Blowfish holst du mit einem Befehl auf den neuesten Stand:

git submodule update --remote --merge

Teste danach mit hugo server -D, ob alles noch passt, bevor du die Seite neu hochlädst.

Erscheint beim Bauen eine Warnung wie Module "blowfish" is not compatible with this Hugo version, ist deine Hugo-Version neuer als die, die das Theme offiziell getestet hat. Meist funktioniert trotzdem alles. Prüfe die Seite einmal gründlich, und warte im Zweifel auf das nächste Update von Blowfish.

Häufige Fehler
#

TOCSS: failed to transform: Du nutzt die Standard-Version statt Hugo Extended. Installiere die Extended-Variante.

Leere weiße Seite: Das Theme ist nicht eingebunden. Prüfe, ob in config/_default/hugo.toml die Zeile theme = "blowfish" aktiv ist und der Ordner themes/blowfish Dateien enthält. Nach einem git clone deines Projekts holst du das Submodul mit git submodule update --init --recursive.

REF_NOT_FOUND beim Bauen: Ein interner Link per ref zeigt auf einen Beitrag, den es nicht gibt. Hugo sucht dabei nach dem Ordnernamen des Beitrags, nicht nach dem Slug.

Beitrag erscheint nicht: Steht im Kopfbereich noch draft: true, oder liegt das Datum in der Zukunft? Beides blendet Hugo beim normalen Bauen aus.

RSYNC Befehl
#

cd ~/git/hugo/patrickadams.de && rm -rf public resources && hugo --gc --minify && rsync -avz --delete --exclude='.well-known' public/ patrickadams@patrickadams.de:/home/patrickadams/htdocs/www.patrickadams.de

Verwandte Artikel