Inhalte in Hugo schnell und vorlagenbasiert von der Kommandozeile erstellen

Die Standardinstallation von Hugo enthält ein praktisches Kommandozeilenwerkzeug, mit dem neue Inhalte auf Basis von Vorlagen erstellt werden können. In der offiziellen Terminologie werden diese Vorlagen als Archetypen bezeichnet. Mit ihrer Hilfe werden Dateien automatisch mit relevanten Informationen befüllt, sodass sich Autoren schneller den eigentlichen Inhalten zuwenden können.

Als Templates sind Archetypen mit Layouts vergleichbar, und es können in ihnen die gleichen Template-Ausdrücke verwendet werden. Ihr Hauptzweck liegt darin, die Frontmatter zu erstellen. Damit sind sie abzugrenzen von Layouts, die in der Regel für standardisierbare Inhalte die bessere Wahl sind.

Das Tool dient dazu, eine neue Seite anzulegen. Im einfachsten Fall wird dazu eine Markdown-Datei erstellt, was im Fokus dieses Artikels steht. Darüber hinaus können damit sogenannte Seitenbündel (Page Bundles) erstellt werden – Verzeichnisse, die eine Einzelseite repräsentieren. Auch auf diese Möglichkeit werden wir im weiteren Verlauf eingehen.

Zusätzlich kann das Werkzeug genutzt werden, um eine neue Hugo-Webseite oder ein neues Hugo-Theme mit allen erforderlichen Dateien anzulegen. Da diese Verwendungsweisen recht selbsterklärend sind, werden sie im Folgenden nicht weiter thematisiert.

Verwendung des Werkzeugs

Das Tool zur Erstellung von Inhalten kann vom Wurzelverzeichnis der Webseite ausgeführt werden. Der Befehl dazu folgt dem folgenden Muster:

hugo new content [flags] [path]

Wie einleitend angesprochen werden die neuen Dateien auf Basis von Vorlagen mit Inhalten befüllt. Dabei handelt sich sich um Markdown-Dateien, die unter archetypes/ angelegt werden.

Ähnlich wie Layouts können auch Archetypen automatisiert verwendet werden. Dazu ist die erste Pfad-Komponente (die Top-Level-Sektion) entscheidend. Wenn es einen gleichnamigen Archetypen gibt, dann werden die neuen Inhalte auf dessen Basis erstellt.

Archetypen greifen auch für Layouts auf tieferen Ebenen der Verzeichnisstruktur. Wenn archetypes/blog.md existiert, so wird es deshalb im folgenden Beispiel automatisch genutzt:

hugo new content blog/2024/post-1.md

Leider lassen sich Archetypen nicht so spezifisch auf Inhalte zuschneiden, wie es bei Layouts der Fall ist. Vielleicht würde man erwarten, dass man archetypes/blog/list.md oder archetypes/blog/_index.md anlegen kann, um es für _index-Dateien unter blog/ zu nutzen. Doch die Lookup Order für Archetypen ist weitaus einfacher gestrickt.

Wir können jedoch dem Aufbau wie bei Layouts folgen. Allerdings müssen wir dafür den anzuwendenden Archetyp ausdrücklich auswählen. Dazu können wir das --kind-Flag nutzen:

hugo new content --kind blog/list blog/2024/_index.md

Tatsächlich können wir auf diese Weise beliebige Archetypen nutzen. Für eine vorhersagbare Anordnung empfiehlt es sich jedoch, die vorgebene Strukturierung von Layouts auch bei Archetypen einzuhalten.

Falls kein zutreffender Archetyp gefunden oder festgelegt wird, erstellt Hugo den neuen Inhalt basierend auf einem Standard-Archetyp. Dieser ist unter archetypes/default.md definiert.

Anwendungsbeispiele

In Archetypen können {{ ... }}-Ausdrücke genutzt werden, ganz wie in Layouts. In ihrem Kontext stehen vier Informationen ohne Weiteres zur Verfügung:

• Der aktuelle Zeitpunkt (im RFC3339-Format)
• Informationen über die zu erstellende Datei (etwa der Dateiname)
• Der Typ, der sich aus der ersten Pfad-Komponente oder der --kind-Setzung ergibt
• Das Objekt, das die gesamte Webseite repräsentiert und aus aus dem sich mit vordefinierten Methoden Informationen abrufen lassen

Mit diesen Daten lassen sich viele der typischen Anforderungen leicht umsetzen. Im Folgenden werden einige praktische Anwendungsbeispiele erläutert.

Veröffentlichungsdatum

Die offizielle Dokumentation empfiehlt, in der Frontmatter jeder Seite neben dem Titel (title) auch das Veröffentlichungsdatum (date) festzuhalten. Prinzipiell lässt sich diese Information direkt aus dem Kontext entnehmen:

date: '{{ .Date }}'

Allerdings ist der Rückgabewert der verwendeten Methode sehr präzise und könnte in etwa so aussehen: '2023-08-24T11:49:46-07:00'. Wer eine einfachere Darstellung bevorzugt, kann den Wert mit time.Now in ein anderes Format umwandeln. Für die meisten Zwecke reicht ein Datum ohne Uhrzeit völlig aus:

date: '{{ time.Now.Format "2006-01-02" }}'

Veröffentlichungsstatus

Vermutlich möchten wir die eben erstellten Inhalte nicht sofort auf der Webseite veröffentlichen. In Hugo erreicht man dies, indem man sie als Draft deklariert. Das entsprechende Frontmatter-Feld ist daher typischer Bestandteil von Archetypen und verhindert die direkte Veröffentlichung:

draft: true

Wenn die Arbeit an der Seite abgeschlossen wurde, kann das Feld entfernt werden.

Weitere Felder betreffen den Veröffentlichungsstatus. Mit publishDate lässt sich festlegen, ab welchem Datum eine Seite auf der Webseite abrufbar ist. Umgekehrt kann man mit expiryDate ein Datum definiert werden, ab dem die Seite nicht mehr angezeigt wird. Archetypen für bestimmte Inhalte können davon Gebrauch machen, etwa um Blogbeiträge am kommenden Mittwoch um eine bestimmte Uhrzeit zu veröffentlichen.

Titel

Der Titel ist die zweite Metainformation, die in jeder Frontmatter eingefügt werden sollte. Auch hier helfen Archetypen.

Für das Englische funktioniert das wunderbar. Wie oben angesprochen, steht im Kontext von Archetypen der Dateiname der zu erstellenden Datei zur Verfügung. Wir können - oder _ durch Leerzeichen ersetzen und den String im Anschluss mit der eingebauten title-Funktion in den sogenannten Title Case umwandeln.

title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'

Mit der Ausnahme von Artikeln (“a”, “an”, “the”), Präpositionen (“in”, “for” etc.) und Konjunktionen (“and”, “but”, “or”), werden alle Wörter dabei großgeschrieben. Auch das erste Wort wird großgeschrieben, egal um welches es sich handelt. Damit würde aus to-kill-a-mockingbird.md eine Datei, in der title den Wert 'To Kill a Mockingbird' erhält.

Die Schreibweise erhält ihren Namen daher, dass es sich um ein im englischsprachigen Raum weit verbreitetes Format für Titel handelt. Für Deutsch und andere Sprachen ist die title-Funktion weniger hilfreich. Das liegt vor allem daran, dass ihr kein echtes Part-of-Speech-Tagging vorausgeht. Das heißt die Funktion “weiß” nicht, welche Wörter großgeschrieben werden sollten. Somit würden alle Wörter großgeschrieben, was nicht im Sinne der meisten Anwender sein dürfte.

Es ist in der Regel weniger aufwändig, Nomen und Eigennamen per Hand groß zu schreiben, statt Wörter aller anderen Wortarten manuell wieder klein schreiben zu müssen. Hinzu kommt, dass Dateinamen gar nicht unbedingt dem Titel entsprechen. Aus diesen Gründen ist es für das Deutsche einfacher, im Archetyp einen festen Platzhalter einzufügen:

title: TITEL

Archetypen für Seitenbündel

Bisher wurden mit dem Kommandozeilenwerkzeug Dateien erstellt. Wie einleitend erwähnt kann es auch genutzt werden, um Verzeichnisse anzulegen. Genauer lassen sich damit Verzeichnisse erstellen, die für eine Einzelseite stehen (sogenannte Leaf Bundles). Für ganze Sektionen (Branch Bundles) sind Archetypen nicht vorgesehen.

Seitenbündel dieser Art sind im Wesentlichen Verzeichnisse, die eine index.md und null oder mehr weitere Dateien und Unterverzeichnisse enthalten. Für die Index-Datei und die weiteren eventuell enthaltenen Markup-Dateien können wie bei gewöhnlichen Datei-Archetypen die Template-Ausdrücke verwendet werden. Alle anderen Dateien werden eins-zu-eins ans Ziel kopiert.

Die offizielle Dokumentation gibt ein Beispiel, bei dem ein Archetyp mit index.md und einem images/-Unterverzeichnis unter layouts/galleries/ angelegt wird. Dieser Archetyp wird genutzt, um ein Seitenbündel zu erstellen:

hugo new galleries/bryce-canyon

Das Ergebnis ist ein Verzeichnis unter content/galleries/bryce-canyon, das die gleichen Dateien und Unterverzeichnisse enthält wie die Vorlage und deren index.md wie ein gewöhnlicher Archetyp umgewandelt wurde.

Wie bei Datei-Archetypen können damit auch Seitenbündel auf tieferen Ebenen der Verzeichnisstruktur erstellt werden. Der folgende Befehl würde das exakt gleiche Verzeichnis zwei Ebenen tiefer erstellen:

hugo new galleries/a/b/bryce-canyon

Wie zuvor entscheidet die erste Pfad-Komponente darüber, welcher Archetyp verwendet wird. Und erneut kann das --kind-Flag genutzt werden, um den zu verwendenden Archetyp gezielt auszuwählen.

hugo new --kind other-archetype galleries/a/b/bryce-canyon

Das Resultat dieses Befehls wäre erneut das Verzeichnis unter content/galleries/a/b/bryce-canyon. Der Inhalt dieses neuen Verzeichnisses ergibt sich aber aus dem Inhalt von archetypes/other-archetype/.