Zum Inhalt springen

Einleitung

Im ersten Teil habe ich das Design sowie die verwendeten Frontend-Technologien meiner Fotografie-Website www.sebastiankleinphotography.com vorgestellt.

In diesem zweiten Beitrag beschreibe die Umsetzung mit dem Eleventy Static Site Generator, inklusive:

  • Hervorhebung einiger Eigenschaften von Eleventy
  • Mein Vorgehen bei der Einrichtung
  • Individuelle Lösungen für das Portfolio
  • Stolpersteine, ihre Ursache und Lösung

Als TYPO3-Entwickler werde ich vereinzelt Vergleiche zur Arbeit mit diesem CMS ziehen.

Von LAMP zum Jamstack

Üblicherweise entwickle und betreue ich Websites auf Basis des TYPO3 CMS. Auch diesen Entwickler-Blog betreibe ich seit 2015 mit TYPO3.

Das Fotografie-Portfolio war eine gute Gelegenheit, ein anderes System kennenzulernen. Zu Beginn hatte ich überlegt, mir eine Symfony-Applikation zu erstellen.
Schnell fiel die Wahl aber auf einen Static Site Generator (SSG): Die hohe Flexibilität im Templating war das ausschlaggebende Argument. Der Verzicht auf eine Datenbank sowie das Deployment statischer HTML-Seiten klangen verlockend.

Warum Eleventy?

Ich muss zugeben, großartig verglichen habe ich die verschiedenen SSG vorher nicht. Mir waren einige Namen bekannt, aber einer wurde von vielen Frontend-Entwicklern wiederholt positiv hervorgehoben: Eleventy.

Das Projekt ist mit zwei weiteren Namen verknüpft:

  • 11ty (die übergreifende Organisation und Community des Projekts)
  • Build Awesome (eine 2026 erfolgte Umbenennung unter dem Mantel von Font Awesome)

Nach einer Prüfung der Features von Eleventy sowie dessen Arbeitsweise habe ich das offizielle Starter-Repository für einen Blog geklont und mit meinen Anpassungen begonnen.

Der Blogbereich ("Notes")

Durch das Starter-Repository hatte ich sofort einen funktionstüchtigen Blog mit Listenansicht, Tags, RSS-Feed sowie Browse-Navigation zum vorherigen und nächsten Post.
Mit der “Draft”-Funktion kann ich in Arbeit befindliche Blogposts markieren: Sie werden dann im Development-Modus gerendert, sind vom Build aber ausgeschlossen.

Eleventy verfügt über einen eigenen Development-Server mit Hot-Reloading-Funktion. Im Development-Modus sind Änderungen sofort sichtbar.

Auf der Grundlage dieses Repositories kann man einen eigenen, unabhängig gehosteten Blog schnell den Start bringen.

Im ersten Schritt habe ich die Blogstruktur an meine Bedürfnisse angepasst und ein separates Seitenlayout für Blogposts eingerichtet. Die Anzeige der drei neuesten Blogbeiträge auf der Startseite hat mir gefallen, daher habe ich sie in mein Portfolio übernommen.

Die Wahl der Template-Sprache

Eleventy unterstützt eine Vielzahl von Template-Formaten, von reinem HTML über Markdown und Liquid bis hin zu eigenen Sprachen.
Dabei muss man sich nicht auf ein Format festlegen, sondern konfiguriert eine Liste der zu verarbeitenden Sprachen.

Wichtig war mir in diesem Projekt, dass ich jederzeit vollen Einfluss auf das finale HTML und Styling behalte. Wenn ich an einer Stelle ein zusätzliches HTML-Attribut benötige oder ein einzelnes Element anders gestalten möchte, nehme ich mir diese Freiheit.

Das ist ein deutlicher Unterschied zu meinem Arbeitsalltag im CMS mit möglichst standardisierten Komponenten und fest definierten Optionen. In einer langfristig betreuten Website mit mehreren Tausend Unterseiten und einem Dutzend Redakteuren benötigst du stabile Strukturen und saubere Inhalte; Custom Code kann dir hier beim Upgrade oder Relaunch das Genick brechen.

Ich schreibe daher alle Templates klassisch mit HTML und nutze die Template-Sprache Nunjucks für Kontrollstrukturen sowie alle weiteren benötigten Funktionen.
Es lassen sich übergreifende Seiten-Layouts sowie kleinere, wiederverwendbare Templates (Includes) definieren – ähnlich zu den Layouts und Partials der Fluid Rendering Engine in TYPO3.

Filter und Shortcodes

Nunjucks gehört zu den Sprachen in Eleventy, die sowohl Filter als auch Shortcodes unterstützen.

Filter sind Funktionen, die auf Variablen angewendet werden können. Dazu gehören die Textverarbeitung von Zeichenketten (nl2br, upper) und die Arbeit mit Arrays und Objekten (sort(), groupby). Einige Filter werden von Nunjucks mitgeliefert, weitere sind in Eleventy frei definierbar. Sie lassen sich zudem miteinander verketten:

<p class="c-photo__description">{{ photo.description | safe | nl2br }}</p>

Shortcodes eignen sich zur Erzeugung wiederkehrender HTML-Strukturen, zur Einbindung von Medien oder zur Verarbeitung übergebener Parameter. Sie sind mit Fluid ViewHelpern oder Fluid Components in TYPO3 vergleichbar.

Ich habe mir gleich drei Shortcodes erstellt, um Bilder in einem gewünschten Format zu generieren. Weiter unten gehe ich näher darauf ein; hier ist ein Anwendungsbeispiel meines Shortcodes imageLargerSide:

{% set altText %}
    {{- photo.alt if photo.alt else photo.title -}}
{% endset %}
{% set viewTransitionName %}view-transition-name: photo-{{ photo.fileSlug }};{% endset %}
{% imageLargerSide photo.image, altText, 320,
    { formats: ["avif", "webp", "auto"] },
    { class: "c-photo-list__img", style: viewTransitionName } %}

Verzeichnisstruktur

Ich habe die Verzeichnisse für Eleventy wie folgt konfiguriert:

KonfigurationWertBeschreibung
dir.input_srcSource-Dateien (Templates, SCSS, JavaScript, Bilder, Webfonts, …).
dir.includes_includesTemplates in diesem Unterverzeichnis werden von Eleventy nicht direkt umgewandelt. Sinnvoll etwa für Seitenlayouts, die auf verschiedene Templates angewendet werden. (Pfad relativ zu dir.input)
dir.data_dataVerzeichnis für Daten, die global in allen Templates verfügbar sind. Hier liegen beispielsweise meine Foto-Metadaten. (Pfad relativ zu dir.input)
dir.output_siteZiel-Verzeichnis für den Build-Prozess.

Innerhalb des Input-Verzeichnisses wandelt Eleventy automatisch alle Dateien zu HTML-Dokumenten um, deren Sprache als Template-Format konfiguriert wurde.

Zur besseren Übersicht habe ich die in den Screenshots gezeigten Dateinamen eingefärbt.

  • Gelb: Wiederverwendbare Template-Includes
  • Grün: Seiten (werden umgewandelt zu HTML-Dokumenten, robots.txt, …)
  • Blau: Daten (siehe Datenquellen)
  • Violett: Assets (Stylesheets, JavaScript, Bilder, Icons, …)

In den Screenshots seht ihr zwei “img”-Verzeichnisse. Der erste unterhalb des Input-Verzeichnisses (_src) enthält unter anderem alle Fotos der Bildergalerien – beim Eleventy-Build werden diese Bilder auf die finalen Größen optimiert und zu AVIF/WebP konvertiert. Die Bilder und weiteren Dateien unterhalb von “public” werden von Eleventy (und Vite) nicht weiter verarbeitet, sondern direkt ins Zielverzeichnis kopiert. Das empfiehlt sich für Favicons oder bereits optimierte Open-Graph-Bilder.

Das Kopieren statischer Dateien ist möglich über die Konfiguration von addPassthroughCopy() (Eleventy-Dokumentation); bei Verwendung von Vite über publicDir (Vite-Dokumentation).

Standardmäßig ist der URL-Pfad der generierten Seite identisch mit der Struktur im Input-Verzeichnis.

Über den permalink-Key lässt sich ein abweichender Pfad definieren:

permalink: "/album/new-york-city-the-polaroids-2015/"

Der Build-Prozess schreibt das HTML-Template dann in dieses Verzeichnis. Eleventy wird einen Fehler melden, falls versehentlich mehrere Templates denselben Zielpfad besitzen.

Datenquellen

Daten können mit Eleventy auf verschiedene Weise in Templates bereitgestellt werden.

Bevor Eleventy die Templates rendert, werden die Daten aus allen Quellen zusammengeführt (Data Cascade). Bei mehrfach definierten Daten gibt es eine Priorisierung von lokal nach global.

Global definierte Default-Werte kann ich daher in ausgewählten Verzeichnissen (über *.11tydata.js) sowie in einem einzelnen Template (mit Frontmatter) überschreiben.

Das verwende ich beispielsweise für individuelle Seitentitel, ein abweichendes Layout für den Blogbereich sowie die Zuweisung von Open-Graph-Bildern.

Rendering der Bildergalerien

Pflege der Foto-Metadaten

Die Metadaten aller Fotos aus den Bildergalerien werden in Markdown-Dateien mit YAML Frontmatter geschrieben und zentral im Data-Verzeichnis abgelegt.

Ein JavaScript liest und validiert diese Metadaten. Alle gefundenen Fotos werden anhand ihres Aufnahmedatums sortiert. Zuletzt wird das vorherige und nächste Foto ermittelt, um die Browse-Navigation in der Foto-Detailansicht zu ermöglichen.

_src/_data/photos/paris-2026/paris-2026-polyphemus.md:

---
date: 2026-06-20
title: Polyphemus surprising Acis and Galatea
description: |
    Fontaine Médicis, Jardin du Luxembourg.
    Paris 2026.
alt: "Group of statues at Fontaine Médicis, representing figures from Greek mythology. The giant Polyphemus, in bronze, gazes down at the lovers Acis and Galatea, sculpted in white marble."
image: "/img/gallery/paris-2026/paris-2026-polyphemus.jpg"
dateTaken: "2026-03-28"
album: album.paris2026
genre: [ "Travel" ]
media: "Film"
film: film.portra160
camera: camera.sl66
lens: lens.rollei80
aperture: 4.8
shutter: "1/250"
iso: 160
---

Während dateTaken den Zeitpunkt der Aufnahme enthält (optional im Format “YYYY-MM”), dient date als Datum der letzten Änderung für die Sitemap.

Damit die Bezeichnungen von Filmen, Kameras und Objektiven stets einheitlich ausgegeben werden, sind sie in separaten JS-Dateien definiert. Im Frontmatter werden die Bezeichnungen anhand des Keys (z.B. film.portra160) referenziert.

Genres und Medientypen werden mit den aktuellen Listen abgeglichen, um Dopplungen bei Tippfehlern zu vermeiden ("Landscape" vs “Landscapes”).

_src/_data/genreDescriptions.js:

export default {
    Landscape: {
        text: "",
        featuredImage: "/img/gallery/iceland-2024/iceland-2024-mountains-at-svinafellsjoekull-1.jpg",
    },
    Portrait: {
        text: "",
        featuredImage: "/img/gallery/paris-2026/paris-2026-blossoms-phone.jpg",
    },
    Street: {
        text: "",
        featuredImage: "/img/gallery/nyc-2015-polaroids/pola-nyc2015-crossing.jpg",
    },
    // […]
};

Foto-Detailansicht

Im Frontmatter des Templates für die Foto-Detailansicht verwende ich das Pagination-Feature von Eleventy. Als Daten übergebe ich das photos-Objekt, das aus den Foto-Metadaten generiert wurde: Eleventy generiert daraus ein eigenes HTML-Dokument für jedes Foto.
Im Frontmatter lese ich außerdem den Dateinamen der Metadaten-Datei (mit photo.fileSlug) aus und verwende ihn als Teil des Permalinks.

Im eigentlichen Template lese ich dann die einzelnen Eigenschaften jedes Bildes aus und definiere das gewünschte Markup.

---
pagination:
    data: photos
    size: 1
    alias: photo
permalink: "/photo/{{ photo.fileSlug }}/"
eleventyComputed:
    title: "{{ photo.title }} | Photo"
eleventyNavigation:
    parent: "Photos"
---

<div itemscope="itemscope" itemtype="https://schema.org/Photograph">
    <div class="c-section c-section--centered">
        <div class="c-photo-details">
            {% set altText %}
                {{- photo.alt if photo.alt else photo.title -}}
            {% endset %}
            {% set viewTransitionName %}view-transition-name: photo-{{ photo.fileSlug }};{% endset %}
            <div class="c-photo-details__stage {% if photo.media == 'Instant' %}c-photo-details__stage--shadow{% endif %}">
                <!-- "imageLargerSide" is a custom shortcode, explained further below -->
                {% imageLargerSide photo.image, altText, 1200, { widths: [450, 768, 1200] }, { class: "c-photo-details__img", loading: "eager", sizes: "auto", itemprop: "image", style: viewTransitionName } %}
            </div>

            <!-- further markup and photo metadata -->
        </div>
    </div>
</div>

Listenansichten für Media/Genre

Für die beiden Listenansichten habe ich in der Eleventy-Konfiguration zwei Collections ergänzt.

eleventy.config.js:

export default async function (eleventyConfig) {
    eleventyConfig.addCollection("genres", function () {
        return Array.from(new Set(photos.flatMap(photo => photo.genre || []).filter(Boolean))).sort();
    });

    eleventyConfig.addCollection("mediaTypes", function () {
        return Array.from(new Set(photos.map(photo => photo.media).filter(Boolean))).sort();
    });
};

Auch diese Collections übergebe ich in den Nunjucks-Templates an die Eleventy-Pagination, damit für jedes Genre und jeden Medientyp ein eigenes HTML-Dokument generiert wird.

Im globalen Data-Verzeichnis liegen die Dateien mediaDescriptions.js und genreDescriptions.js, deren Inhalte in allen Templates verfügbar sind. Aus diesen Dateien lese ich das “Featured Image” jedes Genres/Medientyps aus, das in doppelter Größe gerendert wird.
Auf die gleiche Weise kann ich Einleitungstexte für jedes Genre pflegen (wozu ich bislang noch nicht gekommen bin).

_src/photos/genre.njk:

---
pagination:
  data: collections.genres
  size: 1
  alias: genre
permalink: "/genre/{{ genre | slug }}/"
eleventyComputed:
    title: "Genre: {{ genre }}"
eleventyNavigation:
    parent: "Photos"
---
<div class="c-section c-section--centered">
    <div class="c-photo-gallery">
        <div class="c-photo-gallery__intro">
            <div class="c-photo-gallery__intro-content">
                <h1><span class="u-font-light">Genre</span><br>
                    {{ genre }}</h1>
                {% if genreDescriptions[genre].text %}
                    {{ genreDescriptions[genre].text | safe }}
                {% endif %}
            </div>
        </div>
        <div class="c-photo-gallery__images">
            <ul class="c-photo-list">
                {% if genreDescriptions[genre].featuredImage %}
                    {% for photo in photos %}
                        {% if photo.image == genreDescriptions[genre].featuredImage %}
                            <!-- renders featured image -->
                        {% endif %}
                    {% endfor %}
                {% endif %}
                {% for photo in photos | sortByDateTakenDesc %}
                    {% if photo.genre and genre in photo.genre %}
                        {% if photo.image != genreDescriptions[genre].featuredImage %}
                            <!-- renders all other images, sorted by date taken -->
                        {% endif %}
                    {% endif %}
                {% endfor %}
            </ul>
        </div>
    </div>
</div>

Fotoalben

Die Alben besitzen ein individuelles Markup und Styling. Sie werden von mir bewusst manuell erstellt.

Das Basis-Layout habe ich erweitert, sodass ich im Frontmatter zusätzliche Stylesheets und JavaScripts referenzieren kann:

---
title: "Iceland 2024"
ogImage: "/img/share/og-album-iceland-2024.png"
permalink: "/album/iceland-2024/"
album: "Iceland"
year: 2024
eleventyNavigation:
    parent: "Photos"
additionalStyleSheets:
    - "/assets/css/add-on/album-iceland2024.scss"
---

Bildtransformation

Eleventy enthält das “Image Utility”-Plugin, das einige nützliche Features für responsive Bilder umfasst:

  • Aus einem Bild können mehrere Bildgrößen generiert werden
  • Ein Bild kann in mehreren Dateiformaten (JPEG, AVIF, WebP, …) gleichzeitig ausgegeben werden
  • Das bestmögliche HTML-Markup (<img> oder <picture>, <source> mit passenden Attributen) wird automatisch anhand der Bildattribute generiert
  • Defaultwerte für Größen und Formate können konfiguriert werden

Zwei Beispiele für Bildangaben in Nunjucks:

<img src="./possum.png" alt="A possum parent and two possum kids hanging from the iconic red balloon" width="600">

<img src="./possum.png" alt="A possum parent and two possum kids hanging from the iconic red balloon"
		 eleventy:widths="420,800" eleventy:formats="webp,avif,jpeg">

Das von Eleventy generierte HTML-Markup:

<img src="/path/to/image/YwgtEzywUG-600.webp"
     alt="A possum parent and two possum kids hanging from the iconic red balloon"
     loading="lazy" decoding="async"
     width="600"  height="1174">

<picture>
    <source type="image/webp"
            srcset="/path/to/image/YwgtEzywUG-420.webp 420w, /path/to/image/YwgtEzywUG-800.webp 800w"
            sizes="auto">
    <source type="image/avif"
            srcset="/path/to/image/YwgtEzywUG-420.avif 420w, /path/to/image/YwgtEzywUG-800.avif 800w"
            sizes="auto">
    <img loading="lazy" decoding="async" src="/path/to/image/YwgtEzywUG-420.jpeg"
         alt="A possum parent and two possum kids hanging from the iconic red balloon"
         width="800" height="1566"
         srcset="/path/to/image/YwgtEzywUG-420.jpeg 420w, /path/to/image/YwgtEzywUG-800.jpeg 800w"
         sizes="auto">
</picture>

Das ist äußerst komfortabel. Es gibt jedoch eine Besonderheit: Alle Bildgrößen werden grundsätzlich als Breite angegeben, die Bildhöhe automatisch ermittelt. Die Angabe der gewünschten Bildhöhe ist nicht möglich.

Dieses Vorgehen ist nachvollziehbar, da das Image Utility responsive Bilder erzeugt und sich deren Ausgabe ebenfalls nach der Browserbreite richtet.

Im Portfolio haben sich zwei Fälle ergeben, die sich für mich in Eleventy nicht direkt umsetzen ließen:

  1. Ein Hochformat und ein Querformat nebeneinander mit derselben Bildhöhe.
  2. Die Auflistung aller Fotos unter Berücksichtigung des Seitenverhältnisses (längere Seite 320px)

Eigene Shortcodes zur Bildausgabe

Als Lösung habe drei Shortcodes für mein Projekt erstellt:

  1. Bildgröße anhand einer definierten Höhe
  2. Bildgröße richtet sich nach der längeren Seite des Originals
  3. Bild mit Lightbox-Link: Das generierte Bild wird verlinkt mit einer höher aufgelösten Version

Ich hatte vor, die Shortcodes zu veröffentlichen und hier zu verlinken. Aktuell sind sie aber zu sehr auf mein Projekt zugeschnitten und müssen für eine generische Nutzung erst angepasst werden.

Frontend-Build mit Vite

Ich schreibe meine Stylesheets immer noch gerne mit SCSS. Ein Grund dafür ist, dass ich einige “interne” Variablen nicht als CSS Custom Properties deklarieren möchte. Zudem verwende ich gerne Mixins, Maps und @for-Schleifen, um gewisse Teile zu abstrahieren.

Es gibt verschiedene Möglichkeiten, SCSS in Eleventy zu transformieren. Die einfachste ist die addWatchTarget()-Funktion, die im Blog-Repository verwendet wird. Verfügbar ist auch eine Sass-Extension.

Meine Anforderungen

Der FE-Build soll Folgendes vornehmen:

  • Minimierung der Stylesheets und JavaScripts (Entfernen von Whitespace und Kommentaren)
  • GZIP-Kompression von CSS, JS und HTML
  • Hashes im Dateinamen der Assets

Vite

Um alle Anforderungen abzudecken, habe ich @11ty/eleventy-plugin-vite und vite-plugin-compression2 konfiguriert.

Die Einrichtung von Vite hat sich allerdings als komplizierter herausgestellt, als ich mir das anfangs vorgestellt hatte. Vor allem bei der Verarbeitung von Bildern hatte ich anfänglich Schwierigkeiten.

Stolpersteine

Nicht alles habe ich von Beginn an korrekt eingerichtet. Vielleicht helfen die nachfolgenden Punkte jemanden, aus meinen Fehlern zu lernen.

Fehlerhafte Bildpfade bei root-relativen Pfaden

Im Blog-Repository existiert nur ein Beispiel für die Verwendung von Bildern. Im vierten Post wird eines referenziert, das im selben Verzeichnis wie das Template liegt:

<img src="./possum.png" alt="">

Ich wollte meine Fotos in einem zentralen Verzeichnis ablegen. Bei deren Verwendung in Templates habe ich versucht, Pfade ausgehend vom Root-Verzeichnis des Projekts zu setzen. Das sorgte im Build aber für falsche Pfade; das Bild konnte entsprechend nicht angezeigt werden:

<!-- Template -->
<img src="/public/img/image.jpg" alt="">

<!-- Generiertes HTML-Dokument -->
<img src="content/public/img/image.jpg" alt="">

Ich bin nicht der Erste, der darüber stolpert. Im dazugehörigen Issue fand ich den Vorschlag, die Verzeichnisstruktur anzupassen.

Die Ursache des Problems ist: Absolute Pfade sind relativ zum Input-Verzeichnis, nicht zum Projekt-Root.

Da bei mir jetzt Bilder und Templates gemeinsam unterhalb von “_src” (dem Input-Verzeichnis) liegen, funktioniert die Angabe von Bildpfaden wie /img/gallery/path/to/image.jpg.

Doppelte Bildtransformation durch Vite

Eine Fehlkonfiguration meinerseits. Die drei Image-Shortcodes haben die generierten Bilder direkt ins Output-Verzeichnis geschrieben. Vite hat diese Bilder beim Build-Prozess erneut verarbeitet, obwohl sie bereits durch das Eleventy Image Utility optimiert waren.

Vite hat meine Lightbox-Bilder gelöscht

Zu Anfang des Jahres gab es ein Problem mit Vite: Bildpfade in Links wurden nicht berücksichtigt (das Issue wurde als Duplikat geschlossen, das Problem im Juni gehoben).

Für mich hieß das bei der Erstellung des Portfolios: Meine Lightbox-Bilder fehlten am Ende des Build-Prozesses. Vite löscht alle Assets, die nicht zugeordnet werden können.

Als Übergangslösung habe ich die verlinkten Bilder vom Lightbox-Shortcode ins “public”-Verzeichnis generieren zu lassen. Als letzter Schritt im Build-Prozess hat ein closeBundle()-Hook die Lightbox-Bilder verschoben und temporäre Dateien und Verzeichnisse weggeräumt.

Inzwischen generieren alle Image-Shortcodes ihre Dateien in das “public”-Verzeichnis , damit Vite sie unverändert in das Ziel-Verzeichnis kopiert.

Meine Shortcodes haben zusätzliche Bildkopien erzeugt

Alle drei Image-Shortcodes haben im ersten Schritt die Dimensionen des Originalbildes ausgelesen:

let metadataOrig = await Image(fullSrc, {
    widths: [null],
    formats: ["jpeg"],
});
let {width: origW, height: origH} = metadataOrig.jpeg[0];

Dieser Aufruf von Image() (aus dem Image Utility) hat aber nicht nur die gewünschten Informationen zurückgegeben, sondern auch ein Bild in Originalgröße erzeugt und in ein neues „img“-Verzeichnis im Projekt-Root gespeichert.

Die Lösung war die Ergänzung von statsOnly: true (Dokumentation).

Schlusswort

Für die erste Veröffentlichung des Portfolios war es nicht entscheidend, alles technisch perfekt umzusetzen. Ich habe bereits mit Verbesserungen begonnen und weitere geplant.

Die Wahl von Eleventy habe ich nicht bereut. Es bietet mir ein schlankes und flexibles Setup. Neue Fotos und Blogbeiträge sind komfortabel pflegbar.

Nachdem dieser Blogbeitrag nun endlich fertiggestellt ist, kann ich mich in der nächsten Zeit um neue Inhalte im Portfolio kümmern. Denn mit der Kamera war ich zwischenzeitlich mehrmals unterwegs.

Zur News-Übersicht