Hugo Setup und Codeberg Workflow im Kurzüberblick

Inhaltsverzeichnis

In diesem Blogpost beschreibe ich euch ein grundlegendes Hugo Setup und die Installation eines Themes. Die Sourcen und Seiteninhalte werden zusätzlich in einem Codeberg Repo abgelegt. Außerdem skizziere ich das Grundgerüst meines Workflows, den ich mir angewöhnt habe, wenn ich Änderungen in Hugo mache, oder neue Beiträge schreibe. Warum Grundgerüst? Ich bin kein Experte, was den Umgang mit Git angeht und es gibt auch nicht DEN einen Workflow im Umgang mit Git und static Websites. Ein typisches Entwicklungsprojekt mit diversen Contributors ist typischerweise um einges komplexer als eine einfache Webseitenhistorie, die noch dazu von nur einem einzigen Autor verändert wird, wie es bei mir der Fall ist.

Wer eine Übersicht über verschiedene Git-Workflows haben möchte, kann sich das hier auf der Webseite von Atlassian ansehen…

Zusätzlich sei noch erwähnt, dass ich bisher noch keine automatischen build und deploy Schritte in den Ablauf eingebracht habe, weder für die Nutzung von Codeberg Pages, noch für das Deployment der Seiten auf den Server eines Webhosters. Ich wollte mir nicht sofort die gesamte Komplexität des Themas einhandeln, sondern erst mal klein starten und dazulernen.

Der Git-Workflow, für den ich mich entschieden habe, ist das Feature Branching. Mir gefällt die Idee, jeden Blogpost (quasi das Feature) zunächst in einen neuen Branch zu packen, der dann gepushed und gemerged wird, wenn die Arbeit an dem Post abgeschlossen ist. Das funktioniert dann vom Ablauf folgendermaßen:

einmalig das Codeberg Repo einrichten:

ich habe auf der Weboberfläche von Codeberg zunächst ein neues privates Repo eingerichtet, indem die Dateien abgelegt werden sollen. In der Weboberfläche kann ich auswählen, dass gleich eine .gitignore Datei angelegt wird, die für Hugo Installationen passt, so wird z.B. das /public Directory beim Versionieren ausgelassen, in dem Hugo die finalen Webseiten erzeugt. Außerdem bietet die Codeberg Weboberfläche direkt die Möglichkeit, das Repo in verschiedenen Entwicklungsumgebungen (ich verwende VSCode) zu öffnen und das Repo auszuchecken. Ich nutze darüber hinaus das Kommandozeilenterminal in VSCode für die Eingabe der Git und Hugo Befehle. Wenn das Repo initial über die Entwicklungsumgebung ausgecheckt ist und ich festgelegt habe, wo es lokal auf dem Rechner abgelegt werden soll, öffnet sich das Ganze als Workspace in VSCode.

wie sieht der wiederkehrende Git-Workflow aus?

  1. ich erzeuge vor jeder Änderung, die ich machen möchte einen neuen Branch: git checkout -b "setup-hugo" hier beispielhaft für das Setup von Hugo
  2. ich nehme die Änderungen vor, die ich machen will, siehe unten: Hugo Projektstrukur erzeugen
  3. sind alle Änderungen gemacht, fügt man sie zum Branch hinzu git add . . fügt alle Änderungen im Projektverzeichnis hinzu
  4. über git status lassen sich die Stände der jeweiligen Veränderungen nachvollziehen, das sieht dann in etwa so aus:
git status
On branch setup-hugo
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
new file: .gitmodules
modified: README.md
new file: archetypes/default.md
new file: assets/avatar.jpeg
new file: content/de/_index.md
new file: content/de/pages/about.md
new file: content/de/pages/impressum.md
new file: content/de/posts/_index.md
new file: hugo.toml
  1. alle Änderungen im Branch comitten: git commit -m "aussagekräftige Commit Message der gemachten Änderungen"
  2. unseren Branch setup-hugo in das Remote Repo in Codeberg pushen: git push origin setup-hugo

Das taucht dann als Pull-Request auf der Codeberg Weboberfläche auf und kann dort gemerged werden.

  1. git checkout mainund git pull ändern dann den Branch in eurer lokalen Umgebung wieder auf den Main Branch und holen die aktuellen Stände aus dem remote Repo.

Diese Schritte wiederholen sich für jede Änderung, die ihr vornehmen wollt immer wieder in dieser Abfolge.

Hugo Projektstruktur erzeugen:

Kommen wie also nun zu dem, was ich oben unter 2. als Änderungen beschrieben habe, wir wollen ja noch eine Webseite anlegen… Wenn ihr das Repo lokal ausgecheckt habt und auf eurem neu angelegten Branch arbeiten wollt, um eure Webseite zu beginnen, öffnet ihr euch eine Kommandozeile für dieses Verzeichnis und legt dort eine neue Hugo Webseitenstruktur an. Da das Verzeichnis durch das auschecken von README und .gitignore nicht leer ist, müsst ihr den --force Parameter verwenden, sonst meldet Hugo einen Fehler:

hugo new site . --force

Ihr seht auf der Konsole dann die entsprechende Ausgabe über die angelegte Struktur, sowie den Hinweis darauf wie man einen lokalen Server startet, um die späteren Seiten anzusehen. Standardport auf dem localhsot ist 1313, sollte der belegt sein, weil z.B. bereits ein Server läuft, dann wählt Hugo einen random Port aus und zeigt ihn in der Konsolenausgabe an.

die Basisinstallation mit einem Theme ausstatten:

Unter hierfindet ihr eine ganze Reihe von Themes, die ihr in eurem Projekt verwenden könnt. Um Themes einzubinden, stehen verschiedene Möglichkeiten zur Verfügung. Ihr könnt die Themes in eure Struktur kopieren (git clone, oder Zip-Datei herunterladen und entpacken), ihr könnt es als git-submodule oder als Hugo-module einbinden, für die jeweiligen Vor- und Nachteile schaut bitte in die Doku, das ist nicht Thema dieses Artikels. Ich entscheide mich hier an dieser Stelle dafür, das Theme als git-submodule in mein Projekt einzubinden, das verwendete Theme hier ist: Hugo blog awesome

git add submodule https://github.com/hugo-sid/hugo-blog-awesome.git themes/hugo-blog-awesome

klont das Themerepo und legt es im Ordner Themes ab. Wichtig: Note You must have the Hugo extended version installed in order to use this theme. This theme uses Sass for styling. With the Hugo extended version, Sass can be transpiled to CSS without any additional tools. Auf die richtige Hugo Version solltet ihr also bei der Auswahl eures Themes achten.

Was nun noch fehlt, sind eine Basiskonfiguration für die Webseite und ein paar Inhalte. Als Startpunkt trägt jedes Theme üblicherweise einen Ordner ÈxampleSite`in sich, in dem die .toml Konfigurationsdatei und ein paar Beispielinhalte enthalten sind, welche Features das Theme unterstützt. Man kann also entweder mit einer leeren .toml Datei im Basisverzeichnis starten, oder die Muster aus dem Themeordner kopieren und anpassen, so mache ich es meistens, wenn ich mit verschiedenen Themes herumspiele.

Habt ihr das Theme für euch eingerichtet und die Konfigurationsdatei auf eure Bedarfe angepasst, wäre ein guter Zeitpunkt, das Ergebnis eurer Arbeit zu comitten und in das remote Repo zu pushen, sie oben Schritte 3. bis 7. Wie ihr das Ergebnis eurer Arbeit und das spätere Aussehen eurer Seiten während der Änderungen immer wieder lokal anschauen könnt, lasse ich aus Vereiinfachungsgründen hier weg, das ist in der Hugo Doku ausreichend beschrieben hugo serve -D ist hier das Stichwort. Damit steht der Workflow für die weitere Arbeit. Mit jeder Änderung an eurer Webseite wiederholen sich die beschriebenen Schritte. Wiebiel Veränderung ihr jeweils in einen Feature-Branch packt, ist euch überlassen. Wer wie ich nicht täglich mit Git arbeitet, dem empfehle ich ein Git-Cheatsheet für die wichtigsten Befehle, die gibt es zu Hauf im Netz zu finden.