--- comments: true pdf: false date: 2025-02-28 authors: - stephan categories: - Dokumentation - Entwicklung - Static Site Generators links: - Decap CMS: https://decapcms.org/ - Hugo: https://gohugo.io/ - iDoc: https://wangchujiang.com/idoc/ - Material for MkDocs: https://squidfunk.github.io/mkdocs-material/ - MkDocs: https://www.mkdocs.org status: new --- # Warum ich auf Static Site Generators setze: Eine persönliche Präferenz ![Hugo Banner](/blog/images/250228-warum-ich-auf-static-site-generators-setze/title.png) In der heutigen Webentwicklung stehen uns zahlreiche Möglichkeiten zur Verfügung, um Websites zu erstellen. Von komplexen Content-Management-Systemen (CMS) wie WordPress bis hin zu vollständigen JavaScript-Frameworks – die Auswahl ist nahezu endlos. Dennoch habe ich in den letzten Jahren eine klare Präferenz entwickelt: Static Site Generators (SSGs). In diesem Artikel möchte ich erklären, warum ich für Dokumentationsseiten, Blogs und sogar komplette Websites auf diese Technologie setze, welche Vor- und Nachteile sie mit sich bringt und welche Tools ich persönlich am liebsten einsetze. ## Was sind Static Site Generators? Bevor ich tiefer einsteige, möchte ich kurz erläutern, was Static Site Generators überhaupt sind. Im Gegensatz zu dynamischen Websites, die bei jedem Aufruf Inhalte aus einer Datenbank laden und serverseitig verarbeiten, erzeugen SSGs bereits während der Entwicklungsphase alle HTML-, CSS- und JavaScript-Dateien. Das Ergebnis ist eine Sammlung statischer Dateien, die einfach auf jedem Webserver bereitgestellt werden können. ## Die Vorteile von Static Site Generators ### Geschwindigkeit und Performance Der wohl offensichtlichste Vorteil statischer Websites ist ihre Geschwindigkeit. Da bei jedem Aufruf keine Datenbankabfragen durchgeführt werden müssen, laden statische Seiten deutlich schneller. Dies führt zu einer besseren Nutzererfahrung und kann sich positiv auf das Suchmaschinenranking auswirken. ### Sicherheit Ohne Datenbank und serverseitige Skripte bieten statische Websites weniger Angriffsfläche für potenzielle Hacker. Probleme wie SQL-Injections oder andere häufige Sicherheitslücken dynamischer Websites existieren bei statischen Seiten schlichtweg nicht. ### Einfaches Hosting und Skalierbarkeit Da statische Websites nur aus einfachen Dateien bestehen, können sie auf praktisch jedem Webserver gehostet werden. Dienste wie GitHub Pages, Netlify oder Vercel bieten sogar kostenloses Hosting für statische Websites an. Zudem lassen sich statische Seiten problemlos über CDNs (Content Delivery Networks) verteilen, was die Skalierbarkeit erheblich verbessert. ### Versionskontrolle und Zusammenarbeit Der gesamte Inhalt einer statischen Website kann in einem Git-Repository verwaltet werden. Dies ermöglicht eine einfache Versionskontrolle und vereinfacht die Zusammenarbeit in Teams. Änderungen können über Pull Requests vorgeschlagen, überprüft und implementiert werden. ### Entwicklerfreundlichkeit Moderne SSGs bieten eine hervorragende Entwicklungsumgebung mit Features wie Hot Reloading, was den Entwicklungsprozess beschleunigt und angenehmer gestaltet. Die Trennung von Inhalt und Präsentation ermöglicht es, sich auf das Wesentliche zu konzentrieren. ### Kosteneffizienz Durch den Wegfall von Datenbanken und komplexen Serveranforderungen sind die Hosting-Kosten für statische Websites in der Regel deutlich niedriger als für dynamische Websites. ### Automatisierung Durch das wohldefinierte Markdown-Format ist es einfach, Dokumente automatisiert zu erstellen und zu befüllen. Beispielsweise für IT-Dokumentationen eine wirklich feine Sache, wenn man in den Tools arbeitet, welche man gewohnt ist und die Ausgabe aggregiert wird und via SSGs ausgespielt wird. ### Optimale Struktur für KI-Integration und Dokumentenverarbeitung Ein besonders wichtiger Vorteil, den ich in meiner Arbeit schätzen gelernt habe, ist die hervorragende Eignung von SSGs für die Integration moderner KI-Funktionen: #### Effiziente Dokumentenstruktur durch Markdown Die Verwendung von Markdown als primäres Dokumentationsformat bietet eine strukturell saubere und semantisch reichhaltige Grundlage: - Die klare Hierarchie durch Überschriftenebenen erleichtert die automatisierte Informationsextraktion - Einheitliche Syntax für Listen, Tabellen und Code-Blöcke ermöglicht präzise Mustererkennungen - Metadaten in YAML-Frontmatter können für Klassifizierung und Kontextualisierung genutzt werden - Die saubere Trennung von Inhalt und Präsentation führt zu konsistenten, maschinenlesbaren Dokumenten Diese Struktur macht Markdown-basierte Dokumentationen wesentlich effizienter für die Verarbeitung durch KI-Systeme als beispielsweise verschachtelte HTML-Dokumente oder proprietäre Formate. #### Nahtlose Integration von KI-Funktionen Die statische Natur der generierten Websites ermöglicht mir die problemlose Integration verschiedener KI-Funktionen: - **Dokumentations-Chatbots**: Ich kann spezialisierte Chatbots einbinden, die auf dem Inhalt meiner Dokumentation trainiert wurden, um sowohl Service-Mitarbeitern als auch Endbenutzern kontextbezogene Hilfestellung zu bieten. - **semantische Suche**: Durch Vektorindizierung der Dokumentation lassen sich fortschrittliche Suchergebnisse erzielen, die auch Bedeutungszusammenhänge erfassen. - **automatische Zusammenfassungen**: Längere Artikel oder komplexe Anleitungen können durch KI auf die wesentlichen Punkte reduziert werden. - **personalisierte Lernpfade**: KI-Systeme können basierend auf dem Nutzerverhalten individuelle Dokumentationspfade vorschlagen. #### KI-unterstützte Dokumentationspflege Besonders wertvoll finde ich den Einsatz von KI-Agenten für die Dokumentationserstellung und -pflege: - **automatische Konsistenzprüfung**: KI-Agenten können die Dokumentation auf Widersprüche oder veraltete Informationen überprüfen. - **Lückenanalyse**: Fehlende Abschnitte oder unzureichend dokumentierte Funktionen können automatisch identifiziert werden. - **stilistische Harmonisierung**: Bei mehreren Autoren kann eine einheitliche Sprache und Terminologie gewährleistet werden. - **schnellere Erstellung**: Durch KI-generierte Erstentwürfe, die anschließend nur noch überprüft und angepasst werden müssen. - **kontinuierliche Verbesserung**: Die regelmäßige Analyse von Nutzeranfragen kann gezielt Hinweise auf Verbesserungsbedarf geben. Die Kombination aus strukturiertem Markdown und modernen KI-Tools hat meine Dokumentationsprozesse revolutioniert und führt zu qualitativ hochwertigeren, präziseren und nutzerfreundlicheren Ergebnissen bei gleichzeitiger Effizienzsteigerung. Recht leicht lässt sich aus der Kombinationen von No-/Low-Code-Anwendungen wie [NocoDB](https://nocodb.com/) oder [SeaTable](https://seatable.io/) in Verbindung mit Workflow-Tools wie [n8n](https://n8n.io/) und den darin enthaltenen KI-Funktionalitäten ein automatisiertes Content-Tooling erstellen, was schnell zum Erfolg führt. In Verbindung mit freien Large-Language-Models auch aus Datenschutz- und Informationssicherheitssicht ein spannendes Thema.
![n8n](/blog/images/250228-warum-ich-auf-static-site-generators-setze/n8n-workflow.png){ width="75%" loading=lazy }
Für reaktionsfaehig.net experimentiere ich mit einem selbst entwickelten Content Creation Agent mit komplett freien Komponenten und LLMs.
!!! tipp "Eine Anmerkung in eigener Sache" Ich bin zwar ein Freund meine Arbeit wo möglich von KI unterstützen zu lassen, doch ich habe als Mensch immer noch das letzte Wort und am Ende auch die Verantwortung. ## Die Nachteile von Static Site Generators Natürlich ist keine Technologie perfekt, und auch SSGs haben ihre Schwachstellen: ### Eingeschränkte Dynamik Der offensichtlichste Nachteil: Statische Websites sind, nun ja, statisch. Funktionen wie Nutzerkonten, Echtzeit-Interaktionen oder komplexe Formulare sind schwieriger zu implementieren. Für viele dieser Anforderungen müssen externe Dienste oder APIs eingebunden werden. ### Build-Zeit Bei größeren Websites kann die Zeit für den Build-Prozess erheblich ansteigen. Bei häufigen Änderungen oder umfangreichen Inhalten kann dies zu Verzögerungen führen. ### Höhere Einstiegshürde Für Nicht-Entwickler ist die Einstiegshürde bei SSGs höher als bei benutzerfreundlichen CMS wie WordPress. Grundkenntnisse in Programmierung, Markdown und der Umgang mit der Kommandozeile sind oft erforderlich. ### Herausforderung der Benutzeroberfläche: Meine Lösung mit Decap CMS
![Decap CMS auf iPad](/blog/images/250228-warum-ich-auf-static-site-generators-setze/decapcms.png){ width="75%" loading=lazy }
Decap CMS erlaubt es mir auch mobil neue Blogposts zu erstellen, zu ändern oder zu entfernen.
Im Vergleich zu traditionellen CMS fehlt den meisten SSGs standardmäßig eine integrierte Benutzeroberfläche für die Content-Erstellung. Dies kann besonders für Nicht-Entwickler eine Hürde darstellen. Um dieses Problem zu lösen, setze ich bei meinen Hugo-basierten Projekten [**Decap CMS**](https://decapcms.org/) (früher bekannt als Netlify CMS) ein. Decap CMS bietet eine benutzerfreundliche Web-Oberfläche, die sich nahtlos in meine statischen Websites integrieren lässt. Es ermöglicht: - Eine intuitive Editor-Erfahrung mit WYSIWYG-Bearbeitung und Markdown-Support - Anpassbare Inhaltsmodelle, die genau zu meiner Hugo-Struktur passen - Git-basierte Speicherung, wobei Änderungen direkt als Commits im Repository landen - Medienverwaltung für Bilder und andere Assets - Benutzerauthentifizierung über Git-Provider (z.B. GitHub, GitLab, Gitea, Forgejo) Durch diese Kombination aus Hugo und Decap CMS erhalte ich das Beste aus beiden Welten: Die Performance und Sicherheit einer statischen Website und gleichzeitig eine benutzerfreundliche Oberfläche für Content-Erstellung und -Verwaltung. Dies macht es auch Teammitgliedern ohne technischen Hintergrund möglich, Inhalte zu bearbeiten, ohne direkt mit Git oder Markdown arbeiten zu müssen. Beruflich habe ich mich mit proprietären Lösungen für diesen Anwendungsbereich auseinandergesetzt. Insbesondere [Directus](https://directus.io/) oder [Sanity](https://www.sanity.io/) kamen hier zum Einsatz. Ich möchte jedoch gerade im privaten Bereich aber auf selbst-gehostete und freie Lösungen setzen und diese ausreitzen. ## Meine bevorzugten Tools im SSG-Ökosystem Im Laufe der Jahre habe ich verschiedene Static Site Generators ausprobiert und für unterschiedliche Anwendungsfälle meine Favoriten gefunden: ### Für Dokumentationen und Websites: (Material for) MkDocs
![Live-Reloading beim Bearbeiten dieses Blogposts](/blog/images/250228-warum-ich-auf-static-site-generators-setze/mkdocs-liveview.png){ width="75%" loading=lazy }
Während ich an diesem Blogbeitrag arbeite, hilft mir das Live-Reloading von MkDocs eine aktuelle Ansicht zu generieren.
**(Material for) MkDocs** hat sich für mich als idealer Generator für Dokumentationen und allgemeine Websites erwiesen. Dieses auf Python basierende Tool überzeugt durch: - Hervorragende Unterstützung für technische Dokumentationen mit brillantem Syntax-Highlighting - Ein modernes, responsives Design basierend auf Google's Material Design - Umfangreiche Suchfunktionalität direkt im Browser - Einfache Navigation und automatische Generierung des Inhaltsverzeichnisses - Ausgezeichnete Markdown-Unterstützung mit vielen Erweiterungen - Zahlreiche Plugins für erweiterte Funktionalität Die klare Struktur und die Fokussierung auf Inhalte machen (Material for) MkDocs besonders für technische Dokumentationen und informationsorientierte Websites zu meiner ersten Wahl. ### Für Blogs und Websites: Hugo ![Hugo Banner](/blog/images/250228-warum-ich-auf-static-site-generators-setze/hugo-logo.png){ width=50%; loading=lazy } Wenn es um Blogs und größere Websites geht, setze ich auf **Hugo**. Dieser in Go geschriebene Generator besticht durch: - Außergewöhnliche Geschwindigkeit beim Build-Prozess, selbst bei tausenden von Seiten - Ein flexibles Taxonomie-System für Kategorien, Tags und benutzerdefinierte Gruppierungen - Umfangreiche Template-Funktionen mit einer leistungsstarken Templating-Sprache - Eine große Auswahl an vorgefertigten Themes - Ausgezeichnete Unterstützung für mehrsprachige Websites - Robuste Asset-Verarbeitung mit integriertem SASS/SCSS-Support - Nahtlose Integration mit Decap CMS für eine benutzerfreundliche Content-Verwaltung Hugo eignet sich besonders für Websites mit häufigen Updates und umfangreichen Inhalten, da der extrem schnelle Build-Prozess den Entwicklungsworkflow erheblich beschleunigt. ### Für Awesome-Sites: iDoc ``` ,, ,, db `7MM MM `7MM ,M""bMM ,pW"Wq. ,p6"bo MM ,AP MM 6W' `Wb 6M' OO MM 8MI MM 8M M8 8M MM `Mb MM YA. ,A9 YM. , .JMML.`Wbmd"MML.`Ybmd9' YMbmd' ``` Für spezialisierte "Awesome"-Seiten (kuratierte Listen mit Tools, Ressourcen etc.) ist **iDoc** mein bevorzugtes Werkzeug. Diese weniger bekannte, aber dennoch leistungsstarke Lösung bietet: - Übersichtliche Darstellung von strukturierten Listen und Ressourcensammlungen - Fokus auf das Wesentliche ohne Ablenkungen - Einfache Möglichkeit, große Mengen an verlinkten Ressourcen zu organisieren - Schnelle Indizierung und effiziente Suchfunktionen - Schlanke und performante Ausgabe iDoc ist perfekt für Projekte, bei denen es primär um die Sammlung und Kategorisierung von Links und Ressourcen geht – genau das, was "Awesome"-Listen ausmacht. ### Weitere SSGs An dieser Stelle möchte ich weitere Static Site Generators aufführen, mit welchen ich mich bereits auseinandergesetzt habe. Ich habe diese nach ihrem Einsatzgebiet eingeteilt: | Einsatzgebiet | Static Site Generator | |----------------------|---------------------------------------------------| | Eher Blogs | [Jekyll](https://jekyllrb.com/), [Hexo](https://hexo.io/), [Pelican](https://getpelican.com/) | | Eher Webseiten | [Astro](https://astro.build/), [Gatsby](https://www.gatsbyjs.com/), [Metalsmith](https://metalsmith.io/), [Middleman](https://middlemanapp.com/) | | Code-Dokumentationen | [Docusaurus](https://docusaurus.io/), [Sphinx](https://www.sphinx-doc.org/en/master/), [DocFX](https://dotnet.github.io/docfx/), [Couscous](https://github.com/CouscousPHP/Couscous), [Daux](https://daux.io/) | | Bücher | [GitBook](https://www.gitbook.com/), [Bookdown](https://bookdown.org/), [mdBook](https://rust-lang.github.io/mdBook/) | ## Mein Workflow mit Static Site Generators Mein typischer Workflow für ein neues Projekt sieht folgendermaßen aus: 1. **Projektinitialisierung**: Auswahl des passenden SSG ((Material for) MkDocs, Hugo oder iDoc) je nach Anforderung und Einrichtung eines Git-Repositories 2. **Grundstruktur**: Erstellung der grundlegenden Navigationsstruktur und Festlegung des Designs (bei Hugo oft durch Auswahl und Anpassung eines Themes) 3. **Content-Organisation**: Strukturierung der Inhalte in einer logischen Verzeichnisstruktur und Erstellung von Markdown-Dateien 4. **CMS-Integration**: Bei Hugo-Projekten Einrichtung von Decap CMS für eine benutzerfreundliche Content-Bearbeitung 5. **Lokale Entwicklung**: Nutzung des integrierten Entwicklungsservers mit Hot-Reloading für schnelles Feedback 6. **Erweiterung durch Plugins**: Integration von zusätzlichen Funktionen über das jeweilige Plugin-System (besonders umfangreich bei (Material for) MkDocs) 7. **KI-gestützte Erstellung und Optimierung**: Einsatz von KI-Tools zur Beschleunigung der Inhaltserstellung, Konsistenzprüfung und Verbesserung der Dokumentationsqualität 8. **Build und Optimierung**: Generierung der statischen Dateien und Optimierung für Performance und SEO 9. **Deployment**: Automatisiertes Deployment über CI/CD-Pipelines (meist über Forgejo/Gitea/GitHub Actions) zu GitHub Pages, Netlify oder einem eigenen Server 10. **Integration von KI-Funktionen**: Einbindung von Chatbots oder anderen KI-basierten Assistenzsystemen für verbesserte Benutzererfahrung Dieser Prozess ermöglicht mir eine effiziente Entwicklung und Wartung meiner Websites, ohne mich um Datenbanken oder komplexe Serverinfrastrukturen kümmern zu müssen. ## Praktische Ergänzungen für mein SSG-Setup Um die Grenzen der statischen Generierung zu erweitern, nutze ich hin und wieder einige selbst-gehostete und Open-Source-Dienste: - **Formularverarbeitung**: Integration von [OpnForm](https://opnform.com/) für datenschutzkonforme Kontaktformulare - **Kommentarsystem**: Verwendung von [ISSO Comments](https://isso-comments.de/) als selbst-gehostete Alternative zu externen Kommentardiensten - **Analytik**: Einbindung von [umami](https://umami.is/) für datenschutzfreundliche und selbst-gehostete Besucherstatistiken - **Suche**: Integration von [**meili**search](https://www.meilisearch.com/) für leistungsstarke und selbst-kontrollierte Suchfunktionen - **Automatisierung**: Nutzung von [Forgejo](https://forgejo.org/) Actions für regelmäßige Aktualisierungen und Veröffentlichungen - **KI-Chatbots**: Einbindung trainierter Assistenzsysteme zur Unterstützung von Servicemitarbeitern und Endnutzern Alle diese Lösungen erlauben mir die volle Kontrolle über die Daten und Infrastruktur, während ich gleichzeitig die Vorteile moderner Technologien nutzen kann. ## Derzeit umgesetzte Projekte und der verwendete SSG | Static Site Generator | Letzte Änderung | Website | | --------------------- | ------------| ------- | | MkDocs | ![Last Commit (main branch)](https://shields.hadan-it.com/gitea/last-commit/web/stephan.hadan.de?path=CHANGELOG&gitea_url=https%3A%2F%2Fgit.hadan-it.com&style=flat&logo=forgejo&label=last%20commit) | [Meine Website](https://stephan.hadan.de/) | | Hugo | ![Last Commit (main branch)](https://shields.hadan-it.com/gitea/last-commit/web/reaktionsfaehig.net?path=CHANGELOG.md&gitea_url=https%3A%2F%2Fgit.hadan-it.com&style=flat&logo=forgejo&label=last%20commit) | [Mein Tech Weblog](https://reaktionsfaehig.net/) | | iDoc | ![Last Commit (main branch)](https://shields.hadan-it.com/gitea/last-commit/public/techstack.hadan.de/main?path=README.md&gitea_url=https%3A%2F%2Fgit.hadan-it.com&style=flat&logo=forgejo&label=last%20commit) | [Mein Techstack](https://techstack.hadan.de) | | Hugo | ![Last Commit (main branch)](https://shields.hadan-it.com/gitea/last-commit/web/iamstephan.info?path=CHANGELOG.md&gitea_url=https%3A%2F%2Fgit.hadan-it.com&style=flat&logo=forgejo&label=last%20commit) | [Meine Web vCard](https://iamstephan.info) | Daneben habe ich beruflich größere Dokumentationen mit (Material for) MkDocs erstellt, die nun einen wahren Datenschatz beherbergen. Derzeit entwickele ich mithilfe von [Astro](https://astro.build/), [Tailwind CSS](https://tailwindcss.com/) und [TinaCMS](https://tina.io/en/home) einen LinkTree-Ersatz mit einer persönlichen Note. ## Fazit: Static Site Generators als moderne Lösung für verschiedene Anwendungsfälle Für mich persönlich bieten Static Site Generators die ideale Balance zwischen Flexibilität, Performance und Wartbarkeit. Mit (Material for) MkDocs für Dokumentationen, Hugo (mit Decap CMS) für Blogs und iDoc für Awesome-Listen habe ich ein Setup gefunden, das praktisch alle meine Anforderungen abdeckt. Die strukturierte Natur von Markdown-Dokumenten in Kombination mit modernen KI-Tools eröffnet zudem völlig neue Möglichkeiten für die Erstellung, Pflege und Nutzung von Dokumentationen. Die automatisierte Konsistenzprüfung, Unterstützung durch spezialisierte Chatbots und effizientere Inhaltserstellung durch KI-Assistenz haben meine Dokumentationsprozesse auf ein neues Level gehoben. Obwohl SSGs nicht für jedes Projekt geeignet sind – insbesondere nicht für hochdynamische Anwendungen mit komplexen Benutzerinteraktionen – haben sie sich für meine Anwendungsfälle als hervorragende Lösung erwiesen. Die kontinuierliche Weiterentwicklung der SSG-Ökosysteme und die zunehmende Integration von KI-basierten Diensten erweitern zudem ständig die Möglichkeiten dieser Technologie. Auch im Bereich Präsentationen gibt es Möglichkeiten via Markdown und entsprechenden Generatoren wie [reveal.js](https://revealjs.com/) oder [Marp](https://marp.app/) ansehnliche Ergebnisse zu erzielen. Ich habe hier bereits beeindruckende und immer aktuelle Präsentationen für IT-Onboardings erstellt. Wer bereit ist, sich mit der anfänglichen Lernkurve auseinanderzusetzen, wird mit einer schnellen, sicheren und wartungsarmen Website belohnt. Aus meiner Perspektive lohnt sich dieser Aufwand definitiv – die Ergebnisse sprechen für sich. Was sind deine Erfahrungen mit Static Site Generators? Hast du andere bevorzugte Tools oder Workflows? Ich freue mich auf deine Kommentare und den Austausch zu diesem Thema!