Einführung

Warum ein statischer Website-Generator und warum Hugo?

  • weil es eine einfache Lösung ist, die funktioniert. Für Visitenkarten-Websites oder Blogs benötigen Sie kein komplexes Backend.
  • Alle Einstellungen in einer Datei hugo.toml oder hugo.yaml in einem deklarativen Stil, sodass alles sehr prägnant ist. Die Formate TOML und YAML sind so einfach, dass Sie eine Site einrichten können, ohne sich mit diesen Formaten befassen zu müssen.
  • Sie müssen sich nicht mit HTML, CSS und JS befassen, um Inhalte zu erstellen. Inhalte werden in .md Markdown-Dateien erstellt. Das Markdown-Format ist deutlich einfacher. Im Internet finden Sie zahlreiche Anleitungen zur Markdown-Syntax. Zum Beispiel hier.
  • Das Programm Hugo ist nur eine einzelne Binärdatei, die in Go geschrieben ist und keine weiteren Abhängigkeiten aufweist. Hugo generiert eine Site sehr schnell.

Installation

Auf der Hugo-Website finden Sie eine hervorragende Anleitung zur Installation von Hugo für verschiedene Betriebssysteme und verschiedene Paketmanager. Es gibt jedoch einen Vorbehalt.
Bei Betriebssystemen wie Debian oder MX Linux liegt der Schwerpunkt auf Stabilität, daher können einige Pakete in ihren Repositories veraltet sein.
Und das Erste, was Sie tun werden, nachdem Sie ein Projekt mit Hugo erstellt haben, ist die Installation eines Site-Designs. Und wenn Hugo eine veraltete Version ist, wird eine beträchtliche Anzahl von Designs nicht richtig funktionieren.
Daher empfehle ich für Betriebssysteme wie Debian oder MX Linux, die neueste stabile Version von Hugo als .deb-Datei aus dem Hugo GitHub-Repository herunterzuladen und zu installieren.
Zusätzlich benötigen Sie Git für Ihr Betriebssystem.

Ein Projekt erstellen

Es ist ganz einfach. Öffnen Sie ein Terminal und führen Sie den Befehl aus

hugo new site <ProjectName>

Hugo erstellt einen Ordner mit dem Namen Ihres Projekts <ProjectName> mit allen erforderlichen Dateien und Ordnern darin. sowie die Konfigurationsdatei hugo.toml.
Damit Hugo ein Projekt mit einer Einstellungsdatei im YAML-Format erstellt, müssen Sie den folgenden Befehl ausführen.

hugo new site <ProjectName> --format yaml

Einige Vorlagen für Hugo bieten Beispiel-Site-Theme-Einstellungen im YAML-Format auf ihren Websites, Daher möchten Sie möglicherweise dieses Format verwenden.

Installieren des Designs

Sie können auf der Hugo-Website ein Design auswählen. Rufen Sie anschließend die Designseite auf und folgen Sie den Installationsanweisungen. Es gibt mehrere Installationsmethoden.
Es lohnt sich, das in der Anleitung empfohlene auszuwählen.
Zum Beispiel für das PeperMod-Thema:

  1. Öffnen Sie ein Terminal und gehen Sie zum Stammverzeichnis des Projektordners
cd <ProjectName>
  1. Initialisieren Sie ein lokales Git-Repository
git init
  1. Installieren Sie das Design als Git-Submodul (empfohlene Methode für dieses Design)
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive
  1. Fügen Sie als nächstes die Zeile zur Konfigurationsdatei hugo.yaml hinzu
theme: ["PaperMod"]

Einstellungen

Die Einstellungen für die gesamte Site befinden sich in der Datei hugo.toml oder hugo.yaml. (Es gibt auch Einstellungen für jede Seite der Site in einer Markdown-Datei.) Der Metadatenblock “front matter” wird in diesem Fall am Anfang der .md-Datei platziert.)
Der Parameter baseURL in der Datei hugo.yaml gibt die Adresse Ihrer veröffentlichten Site an.
Um die Site beispielsweise lokal auszuführen, lauten die Einstellungen wie folgt:

baseURL: http://localhost:1313

Danach können Sie die Site generieren.

hugo

Und starten Sie den Server lokal.

hugo server  # oder 'hugo server --baseURL="http://localhost:1313/"'

Öffnen Sie anschließend Ihre Site im Browser unter der in den Einstellungen angegebenen Adresse.
http://localhost:1313
Die für jedes Design spezifischen Einstellungen werden durch den Parameter params festgelegt.
Es gibt viele Konfigurationsmöglichkeiten, daher werde ich nicht alle beschreiben. Detaillierte Informationen finden Sie auf der Hugo-Website.
Außerdem gibt es auf der PeperMod-Themeseite eine Beispielsite mit Einstellungen für dieses Theme.

Inhaltsfüllung

Der gesamte Inhalt wird im Ordner content gespeichert. Erstellen wir eine neue Seite für die Site mit dem Befehl

hugo new content/FirstPage.md

Hugo erstellt eine Datei auf der Grundlage der Vorlage default.md, die im Ordner archetypes gespeichert ist.
Bearbeiten Sie als Nächstes die Datei FirstPage.md, generieren Sie die Site neu und starten Sie den Server.

hugo
hugo server -D

Die Option -D bedeutet “Als Entwurf markierten Inhalt einschließen”. Wenn Sie mit der Bearbeitung der Datei FirstPage.md fertig sind, sollten Sie den Parameter draft im Metadatenblock “front matter” derselben Datei ändern.

draft: false

Danach wird die Seite auf der Website angezeigt.

Hinzufügen eines Bildes

Alle Bilder werden in den Ordnern static oder assets gespeichert.
Das Titelbild für eine einzelne Seite wird im Metadatenblock .md der Datei angegeben.

cover:
  image: cover.png
  caption: "Seitenumschlag"

Siteweite Bilder werden in hugo.yaml konfiguriert.

params:
  env: production
  images: ["og-default.png"]
  cover:
    hidden: false
  label:
    icon: "logo.svg"
    iconHeight: 45
  assets:
    favicon: "favicon.ico"
    favicon16x16: "favicon.ico"
    favicon32x32: "favicon.ico"

Der Parameter images gibt an, welches Bild für das Cover verwendet wird, wenn der Link in sozialen Netzwerken veröffentlicht wird. Damit diese Einstellung funktioniert, müssen Sie env: production festlegen.
Der Parameter label gibt das Site-Logo an.
Die Parameter favicon, favicon16x16 und favicon32x32 legen das Site-Symbol im Browser-Tab fest.
Bitte beachten Sie, dass favicon, favicon16x16 und favicon32x32 alle angegeben werden müssen, auch wenn es nur ein Bild gibt!
Der Wert des Parameters hidden: false in der Konfiguration ist –

params:
  cover:
    hidden: false

bedeutet, dass standardmäßig Seitencoverbilder angezeigt werden. Für eine einzelne Seite können Sie dieses Verhalten in der .md-Datei der Seite deaktivieren.

Website-Veröffentlichung

Sie können eine Site kostenlos veröffentlichen, beispielsweise auf GitHub Pages.
Dazu müssen Sie auf GitHub ein Konto mit Ihrem UserName und einem Repository namens UserName.github.io erstellen.
Dies ist erforderlich, damit Ihre Site die URL UserName.github.io erhält.
Laden Sie anschließend Ihre Site aus dem Ordner public in Ihrem Projekt in dieses Repository hoch. Hierfür gibt es mehrere Möglichkeiten. Betrachten wir die Option mit zwei Repositories.
Wir erstellen eines im Stammverzeichnis des Projekts für den Quellcode.

cd mywebsite
git init # wenn das Repository noch nicht initialisiert ist
echo "public/" >> .gitignore
git add .
git commit -m "Initial commit."

Der zweite befindet sich im Ordner public.

cd public
git init
git remote add origin git@github.com:username/username.github.io.git
cd ..
hugo
cd public
git add .
git commit -m "Deploy $(date)"
git push origin main --force

Wichtig: --force ist erforderlich, da der Inhalt von public/ bei jeder Ausführung von hugo neu generiert wird.

Eine andere Möglichkeit besteht darin, ein Repository für den Quellcode und zum Veröffentlichen der Site zu verwenden.
Erstellen Sie in diesem Fall einen separaten Repository-Zweig für den generierten Code git checkout -b gh-pages.
Geben Sie auch in diesem Fall in den Repository-Einstellungen auf GitHub Settings -> Pages im Abschnitt Source -> Deploy from a branch den Zweig gh-pages und den Ordner an, in dem sich die Site in diesem Zweig befindet (/ ist das Stammverzeichnis des Projekts).