Wie Webseiten in Hugo aufgebaut sind

Webseiten folgen in ihrem Aufbau einem Muster. Je nach eigenen Anforderungen lässt sich ihre Komplexität schrittweise steigern. Hugo bietet Entwicklern und Autoren nützliche Hilfsmittel, um Besuchern auch umfangreiche Inhalte auf eine übersichtliche Weise zugänglich zu machen.

Ein zentraler Aspekt dieser Inhaltsverwaltung ist die Zuweisung von Arten (kinds) und Typen (types) zu Inhalten. In Hugo erfolgt diese Zuweisung meist automatisch, basierend auf den Dateinamen und der Position der Dateien im Verzeichnisbaum. Die Zuordnung zu einer bestimmten Art oder einem Typ entscheidet über das Layout, das für einen gegebenen Hauptinhalt angewendet wird. Arten und Typen spielen auch eine wesentliche Rolle, wenn neue Inhalte mithilfe von Archetypen erstellt werden.

In diesem Teil der Serie geben wir einen Überblick über die Arten und Typen, die Hugo standardmäßig vergibt. An späterer Stelle wird zudem erläutert, wie man Typen manuell zuweist.

Flache Hierarchien

Zunächst zum einfachsten Fall. Von einem One-Pager spricht man bezüglich Webseiten, die nur eine einzige Hauptseite umfassen. In Hugo wird der Hauptinhalt dieser Seite in der Datei content/_index.md gespeichert. Diese Seite ist über die Basis-URL (z.B. https://example.com/) erreichbar. Da ihr automatisch die Art home zugewiesen wird, wird für sie das home-Layout angewendet.

Viele Webseiten umfassen mehrere Einzelseiten, die unabhängig voneinander bestehen. Auf der Webseite eines Handwerksbetriebs finden sich etwa Unterseiten wie Startseite, Leistungen, Über uns und Kontakt. In Hugo legt man für jede dieser Seiten eine separate Markup-Datei im content/-Verzeichnis an, etwa content/leistungen.md. Diese Seiten werden als Einzelseiten (single pages) behandelt – das bedeutet, dass sie eigenständige Hauptinhalte darstellen. Solche Seiten erhalten automatisch die Art page und verwenden das single-Layout.

Sie sind abzugrenzen von Überblicksseiten, die Einzelseiten auflisten. Allgemein werden sie als Listenseiten (list pages) bezeichnet. Ihnen werden differenziertere Arten zugeordnet (dazu gleich mehr), während ein list-Layout als Fallback definiert werden kann.

Zusätzlich unterscheidet Hugo besondere Arten von Einzelseiten: 404 für eine 404-Fehlerseite, sitemap für die sitemap.xml und robotstxt für die robots.txt. Diese Seiten werden automatisch erzeugt und können durch jeweils gleichnamige Layouts gestaltet werden.

Sektionen

Obwohl viele Inhalte als Einzelseiten für sich stehen, eignen sie sich nicht für die Hauptnavigation. Blogbeiträge sind ein typisches Beispiel, ebenso wie Zeitungsartikel oder einzelne Tutorials auf einem Tech-Portal. Solche Inhalte bilden spezifische Typen von Einzelseiten – Blogbeitrag, Artikel oder Tutorial.

Hugo spricht in diesem Kontext von Sektionen der Webseite. Es handelt sich um Bereiche, deren Inhalte in der Regel thematisch oder stilistisch zusammenpassen. Praktisch werden sie dadurch definiert, dass direkte oder indirekte Unterverzeichnisse im content/-Ordner erstellt werden. Dabei unterscheidet man zwei grundlegende Fälle.

Wird ein Verzeichnis direkt unter content/ erstellt, so ergibt sich daraus ein gleichnamiger Typ von Einzelseite. Typen verhalten sich ähnlich wie Arten, sind aber etwas spezifischer. Zum Beispiel ist der Inhalt von content/blog/post-1.md von der Art page und vom Typ blog. Daraus folgt, dass für post-1.md das blog-Layout angewendet wird, sofern es existiert. Dies gilt auch für Inhalte auf tieferen Ebenen. So ist auch content/blog/2024/post-1.md seinem Typ nach ein Blogpost.

Verzeichnisse, die sich auf tieferen Ebenen des Verzeichnisbaums befinden, repräsentieren dann eine Sektion der Webseite, wenn sie eine Datei namens _index.md enthalten. Diese Markup-Datei erzeugt meist eine Überblicksseite. So würde content/blog/_index.md eine Seite generieren, Blogbeiträge auflistet und über domain.com/blog/ aufgerufen wird. Das section-Layout bestimmt dabei, wie die Einzelseiten des entsprechenden Typs dargestellt werden.

Layouts für Sektionen lassen sich auf vielfache Weise definieren, wobei die folgenden wahrscheinlich am ehesten verwendet würden: layouts/blog/list.html, layouts/_default/blog.html, layouts/_default/section.html. Oder auch das sehr allgemeine layout/_default/list.html, das als Fallback nicht nur für Sektionen, sondern auch für andere Übersichtsseiten fungiert (etwa für Taxonomien).

Mehr Kontrolle über die präsentierten Inhalte einer Sektion

Verzeichnisse direkt unter content/ – Hugo nennt sie: top-level content directories – können eine _index.md enthalten. Anders als bei Sektionen der anderen Art, entscheidet das aber nicht darüber, ob eine entsprechende Überblicksseite verfügbar ist. Falls nicht ausdrücklich deaktiviert (dazu gleich mehr), erzeugt Hugo für alle Top-Level-Sektionen automatisch eine Überblicksseite.

Das ist jedoch nicht immer gewünscht. Nehmen wir die Blog-Section als Beispiel: Statt alle Blogbeiträge auf einer Seite zu präsentieren, könnten wir sie nach Veröffentlichungsjahr strukturieren. Dann könnten wir beispielsweise content/blog/2024/_index.md und content/blog/2023/_index.md anlegen, um für die Sektionen der tieferen Ebenen Überblicksseiten zu generieren. Hugo wird jedoch standardmäßig auch domain.com/blog/ verfügbar machen.

Wollen wir das nicht, so kann content/blog/_index.md genutzt werden, um die Überblicksseite zu deaktivieren.

---
title: "Blog"
_build:
  render: never
  list: never
---

Diese Einstellung bewirkt, dass domain.com/blog/ auf die 404-Fehlerseite führt, während domain.com/blog/2023/ und domain.com/blog/2024/ erreichbar bleiben.

Sektionen sind hilfreich, um Besuchern systematisch die Inhalte eines bestimmten Typs zu präsentieren, besonders wenn es sehr viele Inhalte dieses Typs gibt. In anderen Szenarien, in denen Unterverzeichnisse tieferer Ebenen keine _index.md haben, dienen sie lediglich der Strukturierung von Dateipfaden und URLs. Deshalb haben in Hugo auch Unterverzeichnisse ihren Platz, die keine Sektionen repräsentieren.

Sektionen für die gesamte Webseite deaktivieren

Falls keine Sektionen auf der Seite benötigt werden, lassen sich diese global in der Hauptkonfiguration (hugo.yaml) deaktivieren:

disableKinds: ['section']

Damit werden für Verzeichnisse direkt unter content/ keine automatischen Überblicksseiten mehr erstellt. Wollen wir dennoch eine Überblicksseite nutzen, so können wir für sie weiterhin eine _index.md erzeugen.

Natürlich hat es praktische Konsequenzen, Sektionen grundsätzlich zu deaktivieren. Zu den Funktionen, die daraufhin nicht mehr genutzt werden können, gehören spezifische Layouts (unter layouts/SECTION/), eigene Template-Variablen (.Section und .CurrentSection) und Section-Menüs.

Übrigens können auch andere Arten von automatisch erstellten Inhalten in Hugo auf diese Weise deaktiviert werden. Von den bereits genannten Arten von Inhalten sind das: 404, home, page, robotstxt, rss und sitemap. Im Kontext der Verschlagwortung werden zwei weitere Arten besprochen werden.