Warum ich meinen eigenen Static-Site-Generator gebaut habe

Wer heute eine statische Webseite bauen möchte, hat die Qual der Wahl: Hugo, Eleventy, Astro, Jekyll und viele mehr. Einen weiteren Static-Site-Generator zu schreiben, wirkt auf den ersten Blick wie eine Übung in Eigensinn. Ich habe es trotzdem getan. Das Ergebnis heißt Nera, ist Open Source – und auch diese Webseite wird damit erstellt. In diesem Artikel erkläre ich, was Nera macht, wie es aufgebaut ist und warum ich es gebaut habe.

Warum überhaupt statisch?

Bevor es um Nera geht, kurz zur Grundidee. Ein Static-Site-Generator erzeugt aus Inhalten und Vorlagen fertige HTML-Dateien – einmal, beim Bauen der Seite. Auf dem Server liegen danach nur noch Dateien. Das hat handfeste Vorteile:

• Geschwindigkeit: Der Server liefert fertige Dateien aus, statt bei jedem Aufruf Seiten aus einer Datenbank zusammenzusetzen.
• Sicherheit: Ohne Datenbank, Login-Bereich und serverseitige Skripte gibt es deutlich weniger Angriffsfläche. Es gibt kein Admin-Passwort, das erraten werden kann, und kein Plugin, das ungepatcht vor sich hin altert.
• Wenig Wartung: Keine Datenbank-Updates, keine Sicherheitsupdates für ein CMS im Betrieb.
• Günstiges Hosting: Statische Dateien laufen auf praktisch jedem Webspace.
• Versionierung: Inhalte und Code liegen gemeinsam in Git. Jede Änderung ist nachvollziehbar und umkehrbar.

Natürlich passt das nicht für jedes Projekt. Wenn mehrere Personen ohne technische Kenntnisse regelmäßig Inhalte pflegen, ist ein CMS wie Statamic oder WordPress oft die bessere Wahl. Auch dafür gibt es in meinen Referenzen Beispiele. Für Webseiten, die ich selbst pflege, für Projektseiten und Dokumentationen ist der statische Weg aber ideal.

Warum ein eigener?

Angefangen hat es mit einem ganz konkreten Problem. Für ein Gasthaus hatte ich eine statische Webseite gebaut – reines HTML, denn am Inhalt änderte sich eigentlich nie etwas. Dann sollten auf der Seite Veranstaltungen erscheinen. Jedes Mal das HTML von Hand anzupassen, war nervig und auf Dauer keine Option.

Also habe ich nach der einfachsten möglichen Lösung gesucht. Alles, was ich fand, brachte für diese kleine Aufgabe viel zu viel „Drumherum“ mit. So entstand die erste Version von Nera – eine Versionsnummer gab es damals noch gar nicht. Aus diesem kleinen Werkzeug wurde mit jedem Projekt etwas mehr.

Die Grundidee ist dabei geblieben: Der Kern von Nera soll nur eines tun, nämlich aus Markdown-Dateien statische HTML-Dateien machen. Alles Weitere ist optional.

Ein zweiter Grund ist allgemeiner Natur und gilt für viele Werkzeuge: Wer ein Werkzeug selbst gebaut hat, kennt es bis in die letzte Ecke. Wenn auf einer meiner Seiten etwas nicht wie erwartet funktioniert, muss ich nicht in fremden Foren suchen, sondern weiß, wo ich nachschauen muss. Und ich kann mir genau das bauen, was ich möchte. Ein Beispiel ist das Kontaktformular: Ich mag es, wenn eine Kontaktanfrage einfach als E-Mail verschickt wird. Da lag es nahe, dafür ein eigenes Plugin zu schreiben. Das hat für mich mehrere Vorteile:

• Keine Verarbeitung auf dem Server: Der Webserver liefert nur die Seite aus. Ein Skript, das die Anfrage entgegennimmt und weiterleitet, braucht es nicht.
• Keine gespeicherten Daten: Die Nachricht landet nirgends in einer Datenbank, sondern geht direkt aus dem E-Mail-Programm der Besucherin oder des Besuchers an mich.
• Kein externer Dienst: Kein Formular-Anbieter, an den Daten übermittelt werden, und kein weiterer Vertrag zur Auftragsverarbeitung.
• Ein übersichtliches Projekt: Die Felder des Formulars stehen in einer kurzen YAML-Datei, die Inhalte schreibe ich wie den Rest der Seite in Markdown, das ich wegen seiner Klarheit sehr mag. Gerade bei kleinen und mittleren Webseiten bleibt so alles einfach und überschaubar.

Wie Nera funktioniert

Das Prinzip ist bewusst einfach: Markdown rein, HTML raus.

Inhalte werden als Markdown-Dateien im Ordner pages/ geschrieben. Am Anfang jeder Datei stehen Metadaten im YAML-Format, das sogenannte Frontmatter. Eine Seite sieht zum Beispiel so aus:

---
title: Impressum
layout: pages/default.pug
lang: de
---
Hier steht der eigentliche Inhalt, ganz normal in **Markdown**.

Die Angabe layout bestimmt, mit welcher Vorlage die Seite gerendert wird. Seiten ohne Layout werden nicht als eigene HTML-Datei ausgegeben – das lässt sich nutzen, um wiederverwendbare Textbausteine abzulegen.

Die Vorlagen sind in Pug geschrieben, einer kompakten Template-Sprache, die ohne schließende HTML-Tags auskommt. Die globale Konfiguration liegt in config/app.yaml: Name der Webseite, Übersetzungen, das aktive Design und Optionen wie Asset-Hashing.

Beim Bauen durchläuft Nera vier Schritte: Konfiguration laden, Markdown-Dateien einlesen und umwandeln, Plugins anwenden und schließlich die HTML-Dateien in den Ordner public/ schreiben. Dieser Ordner wird anschließend einfach auf den Webserver hochgeladen.

Plugins statt Funktionsballast

Der Kern von Nera kann bewusst wenig. Alles Weitere kommt über Plugins, die einzeln auf npm unter @nera-static/plugin-* veröffentlicht sind. Diese Webseite nutzt zum Beispiel:

• navigation für Haupt- und Footer-Navigation
• tags für Schlagwörter und die Übersichtsseiten pro Tag
• popular-content für die Teaser-Listen von Leistungen, Referenzen und Blogartikeln
• stacks für wiederverwendbare Inhaltsbausteine
• canonical-links für Canonical- und hreflang-Angaben bei mehrsprachigen Seiten
• link-attributes für Attribute an externen Links
• contact-form für ein Kontaktformular ohne serverseitige Verarbeitung, das beim Absenden das E-Mail-Programm mit einer vorausgefüllten Nachricht öffnet

Jedes Projekt bindet nur ein, was es braucht. Konfiguriert wird jedes Plugin über eine eigene YAML-Datei im Ordner config/.

Ein Paket, eine Kommandozeile

Mit der aktuellen Version ist ein Nera-Projekt bewusst schlank: Ein neues Projekt startet mit genau einer Abhängigkeit, dem Paket @nera-static/nera, das die Kommandozeile mitbringt. Plugins kommen erst dazu, wenn man sie braucht. Angelegt ist ein Projekt mit einem Befehl:

npx @nera-static/nera new my-site
cd my-site
npm run dev

Danach stehen die Befehle nera dev (bauen, lokal ausliefern und bei Änderungen neu bauen), nera build, nera validate (prüft Layouts, Includes und YAML vor dem Veröffentlichen) und nera update zur Verfügung. Ältere Nera-Projekte lassen sich mit nera update --migrate auf das neue Modell umstellen – so ist auch diese Webseite umgezogen.

Designs lassen sich als Themes einbinden. Diese Webseite hat zum Beispiel zwei: das aktuelle Design „Technical Grid“ und das vorherige, zwischen denen ich mit einer Zeile in config/app.yaml wechseln kann.

Was Nera nicht ist – und was noch kommt

Nera ist ein Projekt, das ich neben meiner Arbeit entwickle. Es hat keine riesige Community und kein Ökosystem mit Hunderten Erweiterungen. Wer das braucht, ist mit etablierten Generatoren besser bedient. Wer aber einen kleinen, überschaubaren Generator sucht, den man in kurzer Zeit komplett verstehen kann, ist herzlich eingeladen, es auszuprobieren.

Mit der aktuellen Version bin ich sehr zufrieden, und grundlegende Änderungen erwarte ich nicht mehr. Im Gegenteil: Der neue Aufbau mit einem Paket und einer Kommandozeile macht es einfacher, neue Funktionen hinzuzufügen. An einer arbeite ich bereits: Nera-Webseiten sollen sich künftig auch über eine grafische Oberfläche im Browser bearbeiten lassen. Damit wird der statische Weg auch für Projekte interessant, bei denen heute noch ein klassisches CMS die bessere Wahl ist.

Im Einsatz ist Nera neben dieser Webseite und nera.js.org zum Beispiel bei einem Handwerksunternehmen und einem Versicherungsberater. Ich würde mich riesig freuen, wenn Nera bekannter wird, denn ich glaube, dass gerade der minimalistische Ansatz es von anderen Generatoren unterscheidet. Neue Ideen, Fehlermeldungen und Mitwirkende sind jederzeit willkommen – am einfachsten über ein Issue auf GitHub.

Fazit

Einen eigenen Static-Site-Generator zu bauen, ist keine Entscheidung, die ich jedem empfehlen würde. Für mich hat sie sich gelohnt: Ich habe ein Werkzeug, das genau das tut, was ich brauche, und das ich vollständig verstehe. Die Grundidee statischer Webseiten – schnell, sicher, wartungsarm – gilt aber unabhängig davon, mit welchem Werkzeug sie umgesetzt wird.

Der Quellcode liegt auf GitHub, die Dokumentation auf nera.js.org. Und wenn Sie überlegen, ob eine statische Webseite für Ihr Projekt passt, sprechen Sie mich gerne an.

Ihr Michael Becker