Ressourcenverwaltung

Webseiten verwenden Ressourcen wie Bilder, Videos, PDFs oder andere Dateien. Hugo bietet einen standardisierten Ansatz, wie diese Dateien organisiert und gespeichert werden. Dank vordefinierter Methoden und Funktionen können sie dann direkt auf den Seiten eingebunden werden.

Globale Ressourcen

Einige Ressourcen werden global auf der gesamten Webseite benötigt. So verwenden viele Webseiten zum Beispiel dasselbe Bild als Hintergrund im Titelbereich verschiedener Unterseiten. Für solche Fälle eignet sich das assets/-Verzeichnis, das sich auch für Webseiten mit nur sehr wenigen Ressourcen anbietet.

Auch Stylesheets (assets/css/) und Skripte (assets/js/) werden als Assets betrachtet. Hugo unterscheidet sie terminologisch nicht scharf von Ressourcen. Um ein global verwendbares Stylesheet unter assets/css/main.css einzubinden, kann es etwa mit resources.Get "css/main.css" abgerufen werden. Dabei kommen häufig sogenannte Asset-Pipelines zum Einsatz, etwa um die Größe von Quelldateien zu minimieren.

Seitenbündel

Ein wichtiges Werkzeug zur Ressourcenverwaltung sind sogenannte Seitenbündel (Page Bundles). Dabei handelt es sich im Grunde einfach um Verzeichnisse, die sowohl Markup-Dateien als auch zugehörige Ressourcen enthalten können. Hugo unterscheidet hier zwischen Leaf Bundles und Branch Bundles.

Nicht selten werden Ressourcen nur einmal und nur auf einer bestimmten Einzelseite verwendet. In diesen Fällen ist es sinnvoll, sie direkt bei der entsprechenden Markup-Datei abzulegen. Genau das ist der Zweck der Leaf Bundles. Anstatt wie bisher eine einzelne Datei für einen Hauptinhalt anzulegen (z.B. content/.../name.md), wird für ein Leaf Bundle ein Verzeichnis erstellt, das die Datei content/.../name/index.md enthält. Nach außen hin bleibt alles gleich: Die Seite ist wie bisher unter domain.com/name/ erreichbar.

Der Unterschied liegt nun darin, dass wir im name/-Unterverzeichnis weitere Dateien ablegen können, die wir auf der entsprechenden Seite verwenden wollen. Dabei steht es völlig frei, wie man das Verzeichnis aufbauen möchte. Ein Bild etwa könnte unter content/.../name/images/image-1.png gespeichert werden.

Branch Bundles dienen dem Fall, bei dem mehrere Seiten einer Sektion oder Klasse (dazu gleich mehr) auf geteilte Ressourcen zugreifen. Das wird möglich, wenn in einem Verzeichnis eine _index.md angelegt wird. Für Branch Bundles gilt exakt das gleiche, was eben zu Leaf Bundles gesagt wurde. Auch in diesen Verzeichnissen können weitere Ressourcen abgelegt und in den Markup-Dateien eingebunden werden.

Ressourcen verwenden

Bildressourcen aus Seitenbündeln können in Markdown mit der folgenden Syntax eingebunden werden:

![alt-text](file "title")

Hugo wandelt diese Konstrukte automatisch in HTML um:

<img src="file" alt="alt-text" title="title">

Eine flexiblere Verwendung von Bildressourcen wird durch Shortcodes möglich. Dazu definieren wir unter layouts/partials/render-image.html zunächst ein partielles Layout, das auch Bild-Captchas unterstützt:

{{- $imageURL := .image }}
{{- $altText := .alt | default "" }}
{{- $caption := .caption | default "" }}

<figure class="image-figure">
  <picture>
    <img
      src="{{ $imageURL }}"
      alt="{{ $altText }}"
      loading="lazy"
    >
  </picture>
  {{ with $caption }}
    <figcaption>{{ . | markdownify }}</figcaption>
  {{ end }}
</figure>

Ein Shortcode für Bilder, die direkt aus Seitenbündeln stammen, könnte nun unter shortcodes/images/insert-image.html definiert werden:

{{- $image := .Get 0 }}
{{- $altText := .Get 1 }}
{{- $caption := .Get 2 }}

{{- $pageURL := .Page.RelPermalink }}
{{- $imageURL := printf "%s%s" $pageURL $image }}

{{ partial "images/render-image.html" (dict "image" $imageURL "alt" $altText "caption" $caption) }}

Dieser Shortcode verwendet die Bildressource relativ zum Seitenpfad, ergänzt sie mit Alt-Text und Caption und übergibt die Daten an das zuvor definierte partielle Layout.

Um Bilder aus einem globalen Ordner einzufügen (standardmäßig assets/images), kann ein weiterer Shortcode erstellt werden, der Ressourcen über resources.Get lädt:

{{- $image := .Get 0 }}
{{- $altText := .Get 1 }}
{{- $caption := .Get 2 }}

{{- $imageResource := resources.Get (printf "images/%s" $image) }}

{{- if not $imageResource }}
  {{ errorf "Image '%s' not found in assets/images/" $image }}
{{- end }}

{{ partial "images/render-image.html" (dict "image" $imageResource.Permalink "alt" $altText "caption" $caption) }}

Dieser Shortcode überprüft, ob die Bildressource existiert, und übergibt die absolute URL sowie weitere Metadaten an das partielle Layout. Auf analoge Weise könnten Ressourcen anderer Typen eingefügt werden.

Branch Bundles und Sektionen

Wie bereits gesagt werden Verzeichnisse als Branch Bundles betrachtet, wenn sie eine _index.md enthalten. Aus diesem Grund umfasst jedes Branch Bundle eine Überblicksseite. Die Idee dabei ist wahrscheinlich: Wenn Inhalte auf die gleichen Ressourcen zugreifen, dann gehören sie irgendwie zusammen. Sprich: Sie sind Teil einer Sektion.

Will man das auflistende Verhalten unterbinden, so kann man zu diesem Zweck ein Layout definieren, etwa unter layouts/_default/non-listing.html:

{{ define "main" }}
   <article class="page">
       <header>
           <h1>{{ .Title }}</h1>
       </header>
       <div class="content">
           {{ .Content }}
       </div>
   </article>
{{ end }}

Um das Layout anzuwenden, wird es in der Frontmatter der entsprechenden _index.md ausdrücklich ausgewählt:

---
layout: non-listing
---