Algroveon-Mini-SSG – Wie aus einem Skript ein Werkzeug wurde
Von einem einfachen Python-Skript zum vollständigen statischen Site-Generator mit Mehrsprachigkeit, Übersetzung und Admin-UI.
Zusammenfassung
Der Algroveon-Mini-SSG entwickelte sich von einem einfachen Python-Skript zu einem umfassenden Werkzeug für die Erstellung statischer Websites aus Markdown-Dateien. Das System bietet Funktionen wie eine Browser-basierte Admin-UI, KI-gestützte Übersetzungen und eine strukturierte Handhabung von Mehrsprachigkeit.
Diese Zusammenfassung wurde mit KI-Unterstützung erstellt.
Es fing mit einer Idee und einem kleinen Python-Skript an. Ich wollte weg von den komplexen WordPress-CMS-Seiten, die ich sonst meistens nutze – hin zu einem schlankeren System mit mehr Selbstkontrolle und weniger Ballast. Daraus ist mit der Zeit ein vollständiger Static Site Generator geworden: also ein System, das aus Markdown-Dateien, Templates und Konfiguration eine fertige statische Website erzeugt. Solche Systeme gibt es schon länger am Markt, etwa Hugo, Eleventy, Jekyll oder Astro. Mein System ging mit der Zeit aber in eine etwas andere Richtung – mit Browser-Admin-UI, KI-gestützter Übersetzung und direktem Deploy auf den Webserver. Alles läuft im Browser.
Phase 1: Das Skript
Die ursprüngliche Anforderung war einfach: eine persönliche Website, Inhalte in Markdown, ein paar Jinja2-Templates – also Vorlagen, mit denen sich feste HTML-Strukturen mit variablen Inhalten füllen lassen. Ich brauchte kein Hugo, kein Eleventy und kein großes Framework – nur ein Python-Skript, das Markdown-Dateien einliest und daraus HTML erzeugt. Dass das nicht reichen würde, dazu später mehr.
Phase 2: Mehrsprachigkeit
Die Website sollte Deutsch und Englisch können. Das klingt erst einmal nach wenig Aufwand.
Das eigentliche Problem ist nicht die Übersetzung, sondern die Struktur dahinter. Unter /de/ liegt die deutsche Version, unter /en/ die englische. Die Navigation muss pro Sprache korrekt gerendert werden. Links zwischen Sprachversionen müssen stimmen. Und wenn eine englische Übersetzung fehlt, sollte eine vernünftige Fallback-Logik greifen statt einfach in einer 404-Seite zu enden.
Dazu kamen die Dateinamen. 2024-11-17-mein-artikel.md – da steckt bereits ein Datum drin. Aber was passiert, wenn zusätzlich im Frontmatter – also im Kopfbereich der Markdown-Datei mit Metadaten wie Datum, Titel oder Tags – ein Datum gepflegt wird? Was hat dann Vorrang? Und wie geht man mit europäischen Datumsformaten wie 15.03.2025 oder ausgeschriebenen Datumsangaben auf Deutsch oder Englisch um? Das parse_date-System ist dadurch nach und nach gewachsen und unterstützt heute sechs Formate aus vier Sprachen.
Phase 3: Die Admin-UI
Eigentlich wollte ich nur einen Blogartikel schreiben. Stattdessen musste ich erst das Terminal öffnen, in den richtigen Ordner wechseln, eine Markdown-Datei anlegen, sie im Editor bearbeiten, python build.py ausführen und danach im Browser prüfen, ob alles passt. Für gelegentliches Arbeiten geht das noch, aber auf Dauer ist es kein sinnvoller Workflow.
Die Idee war deshalb simpel: ein kleines Web-Interface, das Dateien auflistet sowie öffnen und speichern kann. Eigentlich ein Nachmittagsprojekt. Am Ende war das die Entscheidung mit der größten Auswirkung auf das gesamte Projekt.
Denn sobald es eine Admin-Oberfläche gab, lag es nahe, dort auch den Build anzustoßen. Dann den Deploy. Dann neue Seiten anzulegen. Dann den Build-Output direkt anzuzeigen. Dann Übersetzungen zu starten. Der Umfang wuchs und wuchs. Heute ist die Admin-UI der eigentliche Dreh- und Angelpunkt des SSG. Build, Deploy, Übersetzung und der gesamte Redaktionsprozess laufen dort zusammen.
Was dabei unerwartet viel Aufwand gemacht hat, war der Markdown-Editor. Ein einfaches textarea hätte technisch gereicht. Mit Split-Live-Preview und einer Toolbar für die häufigsten Formatierungen wird daraus aber ein echtes Werkzeug. Genau dadurch wurde der Editor am Ende zu einem eigenen Teilprojekt – die Geschichte dahinter steht im separaten Markdown-Editor-Artikel.
Phase 4: Deploy ohne Terminal
Den Build hatte ich schnell umgesetzt – ein Button, der build.py aufruft und den Output per SSE-Stream in den Browser schreibt.
Beim Deploy wurde es aufwendiger. FTP und SFTP sind zwei unterschiedliche Protokolle und brauchen unterschiedliche Python-Bibliotheken. Ein inkrementeller Abgleich ist nötig, damit nicht bei jedem Deploy alle Dateien neu hochgeladen werden. MD5-Hashes lösen das grundsätzlich, aber dafür braucht es Logik, die lokale und entfernte Dateien sauber vergleicht. Passwörter wollte ich nicht im Klartext in der Konfiguration ablegen – also OS-Schlüsselbund über keyring. Dazu ein Verbindungstest vor dem eigentlichen Deploy, damit man nicht erst nach einer Minute merkt, dass die Zugangsdaten falsch sind.
Für sich genommen ist nichts davon besonders spektakulär. Aber es sind viele kleine Bausteine, die zuverlässig zusammenspielen müssen. Am Ende steht ein Deploy-Button im Browser, der nach kurzer Zeit meldet, wie viele Dateien hochgeladen wurden und welche übersprungen wurden, weil sie unverändert sind.
Phase 5: Übersetzung per KI
Mehrsprachigkeit bedeutet in der Praxis vor allem doppelten Redaktionsaufwand. Jeden Artikel zusätzlich manuell auf Englisch zu schreiben, ist für ein Hobby-Projekt schlicht zu viel. Deshalb entstand translate.py.
Die erste Version war entsprechend direkt: den kompletten Markdown-Inhalt an die Ollama-API schicken, Übersetzung zurückbekommen, in die Zieldatei schreiben. Das funktionierte – zumindest bei kürzeren Texten. Bei längeren Artikeln litt die Qualität, und manche Modelle begannen, Codeblöcke zu übersetzen oder Frontmatter zu verändern.
Die spätere Logik arbeitet deshalb blockweise und speichert einen SHA-256-Hash des Quellinhalts in der Zieldatei. Wenn sich der Quelltext ändert, erkennt das System die Übersetzung als veraltet und übersetzt gezielt nur diese eine Datei neu – ohne alles andere anzufassen. Codeblöcke bleiben erhalten, Frontmatter-Felder werden selektiv übersetzt oder bewusst ausgeschlossen. Der gesamte Ablauf läuft mit Live-Output im Browser.
Was mich dabei tatsächlich überrascht hat: Wie brauchbar lokale Modelle für so etwas inzwischen sind. Gemma-4 auf einer lokalen Ollama-Instanz liefert bei technischen Texten Übersetzungen, mit denen man vernünftig weiterarbeiten kann. Tonalität und Natürlichkeit brauchen manchmal noch einen zweiten Blick – aber als erster Entwurf ist das bereits ziemlich ordentlich. Alle englischsprachigen Übersetzungen auf dieser Website sind auf diese Weise mit Gemma-4 entstanden.
Was ich heute anders machen würde
Den Scope der Admin-UI früher festlegen. Feature-Creep war der größte Zeitfresser des Projekts. Gleichzeitig hat genau diese Entwicklung dazu geführt, dass das Werkzeug heute im Alltag wirklich trägt – statt nur ein sauberes, aber zu kleines Skript zu bleiben.
Templates von Anfang an sauber trennen. Die Aufteilung zwischen themes/ und site-spezifischen Template-Overrides in sites/<site>/templates/ kam erst relativ spät. Davor war ein Theme faktisch an eine einzelne Site gebunden. Das früher sauber zu trennen, hätte einiges an Refactoring erspart.
Wo es heute steht
Algroveon-Mini-SSG ist längst nicht mehr das 80-Zeilen-Skript vom Anfang. Es ist ein vollständiges Werkzeug mit einem klaren Zweck: die eigene Website bauen, mehrsprachig, ohne externe Dienste und ohne klassische Build-Toolchain.
Ob das für andere sinnvoll ist? Vielleicht . Wer einfach nur eine persönliche Website bauen will, ist mit Wordpress sehr wahrscheinlich besser bedient, vor allem als Einsteiger. Einen eigenen Generator zu schreiben, ist kein rationaler Standardweg zur Website. In meinem Fall war es ein Lernprojekt, das mit der Zeit produktiv geworden ist.
Was noch fehlt: ein inkrementeller Build, ein formales Plugin-System und eine robustere Fehlerbehandlung bei kaputten Markdown-Dateien. Das sind die Punkte, die irgendwann kommen, wenn der Leidensdruck groß genug wird. Bis dahin gilt: Es läuft.