Nachtrag zur Obsidian-Serie. In Teil 5 ist aus Markdown-Dateien ein Blog geworden – mit Quartz als Generator. Jetzt zieht der Unterbau um: von Quartz 4 auf Quartz 5.
Es gab keinen Zwang. Quartz 4 lief stabil, der Blog war live, nichts war kaputt. Trotzdem habe ich umgebaut – und genau das ist der Punkt: Quartz 5 ist kein Update, das man nebenbei einspielt. Es ist eine andere Architektur.
Der Diff zwischen den Versionen umfasst über 250 Dateien. Die Dateien, die ich in Version 4 angepasst hatte, existieren in Version 5 schlicht nicht mehr. Wer „upgraden” will, baut in Wahrheit neu auf. Deshalb wurde aus einem Update ein eigenes Projekt mit Plan, Prototyp und Sicherheitsnetz.
Was sich grundlegend ändert
Drei Dinge verschieben sich von Grund auf:
- Config: Früher zwei TypeScript-Dateien (
quartz.config.ts,quartz.layout.ts). Jetzt eine YAML-Datei. Wo ich vorher Code geschrieben habe, schreibe ich heute Konfiguration. - Plugins: Quartz 5 hat einen schlanken Kern. Alles andere – Explorer, Inhaltsverzeichnis, Graph – kommt aus einem Community-Ökosystem und wird per Git installiert. Updates landen nur noch hier.
- Komponenten: Eigene Bausteine sind nicht mehr Dateien, die man in den Quartz-Code hineinschummelt, sondern eigenständige kleine Plugins.
Das klingt nach mehr Arbeit. In der Praxis ist es weniger – wenn man einmal umgestellt hat.
Aus dem Patch wird Konfiguration
Das schönste Beispiel ist das Inhaltsverzeichnis. In Version 4 wollte ich es standardmäßig eingeklappt. Dafür musste ich eine Komponente patchen und eigenes CSS dazulegen – ein Eingriff in fremden Code, der bei jedem Update wieder brechen kann.
In Version 5 ist daraus das hier geworden:
options:
collapseByDefault: trueDrei Zeilen Konfiguration statt eines Code-Patches. Das ist die eigentliche Pointe der neuen Version: Vieles, was vorher ein gepflegter Eingriff war, ist jetzt eine deklarative Einstellung. Weniger Wartung, kein TypeScript-Zwang, nichts, was beim nächsten Update kaputtgeht.
Auch das Theme zog fast vollständig um: Mein Orange-Akzent steht jetzt sauber in der YAML, die Lese-Spalte von 720 Pixeln und der Typografie-Feinschliff blieben unverändert SCSS und ließen sich 1:1 übernehmen.
Vier kleine eigene Plugins
Nicht alles ließ sich wegkonfigurieren. Was in Version 4 Custom-Komponenten waren, habe ich als lokale Plugins neu geschrieben – kleine, in sich geschlossene Bausteine:
- die „Über”-Box in der Seitenleiste mit den Social-Icons,
- die Archiv-Seite, die alle Artikel chronologisch listet,
- einen Fork der „Letzte Artikel”-Liste, der zusätzlich die Beschreibung anzeigt und Sonderseiten ausblendet,
- und einen Untertitel, der den ersten Satz der Beschreibung unter jede Überschrift setzt.
Vier Posten, alle überschaubar. Das ist der ehrliche Preis der Migration – aber es ist ein einmaliger.
Eine bewusste Entscheidung: Graph statt Explorer
Beim Aufräumen habe ich eine inhaltliche Entscheidung getroffen. Die alte Seitenleiste war mir zu voll. Statt eines Ordnerbaums (Explorer) steht jetzt die Graph-Ansicht prominent links – das Netz der verlinkten Artikel als interaktive Karte.
Das passt zur Idee, die diesen ganzen Blog trägt: Wissen ist kein Ordner, sondern ein Netz. Wer mehr dazu wissen will, warum ich überhaupt so schreibe, findet das in Das zweite Gehirn und in meiner PKM-Serie.
Nur: Ein Graph ist genau so lebendig wie die Verlinkung dahinter. Beim ersten Build war er fast leer – ein einzelner Punkt. Denn meine Artikel hingen bisher vor allem an Tags, kaum aneinander. Die unmittelbare Lösung war, die Tags als Knoten mitzuzeichnen. Die richtige Lösung ist eine andere: mehr Querverweise zwischen den Artikeln. Daran arbeite ich jetzt – Schritt für Schritt durch alle Texte.
Zwei Stolpersteine
Migrationen verlaufen nie glatt, und die lehrreichen Momente sind die, in denen etwas Unerwartetes passiert.
Erstens: Eine Komponente, die ich nur ausblenden wollte, ließ sich nicht einfach abschalten. Setzte ich sie auf „deaktiviert”, brach plötzlich der halbe Build zusammen – statt über 400 Seiten kamen nur noch knapp 170 heraus, und Überschriften verschwanden. Der Grund: Das Plugin war nicht nur Anzeige, sondern zugleich ein Transformer, von dem andere Bausteine abhingen. Die Lösung war nicht „aus”, sondern eine eigene Option, die nur die Ansicht versteckt.
Zweitens: Eine CSS-Regel wollte partout nicht greifen. Ich hatte sie auf ein Element gemünzt, das – so meine Annahme – direkt unter einem bestimmten Container der Seite hängt. Im tatsächlichen HTML schob sich dort aber noch ein Wrapper dazwischen. Mein Selektor verlangte ausdrücklich das direkte Kind (das > in CSS) und fand deshalb nie ein passendes Element – die Regel war fehlerfrei geschrieben und trotzdem komplett wirkungslos. Der Bug saß nicht im Code, sondern in meiner Vorstellung vom Aufbau der Seite.
Cutover ohne Angst
Das Schönste an dieser Deploy-Kette: Sie macht Mut zum Risiko, weil sie keines ist. Der Build ist von der Versionsverwaltung entkoppelt – ein Git-Push allein veröffentlicht nichts. Live geht es erst mit einem einzigen Wrangler-Befehl, und Cloudflare bewahrt jedes alte Deployment auf. Falls etwas schiefgeht, ist die vorherige Version einen Klick entfernt.
So lief auch der Umstieg: Prototyp in einem getrennten Verzeichnis aufbauen, gegen das Live-Bild prüfen, und erst nach gründlichem Test deployen. Die alte Version 4 liegt weiter als Fallback daneben.
Fazit
Von außen sieht der Blog fast gleich aus – das war das Ziel: volle Parität. Von innen steht er auf einer saubereren Grundlage. Weniger Code-Patches, mehr Konfiguration, ein gepflegtes Plugin-Ökosystem, das die Updates trägt.
Und die Graph-Ansicht ist jetzt nicht nur Dekoration, sondern eine Einladung: Schreib so, dass die Texte aufeinander zeigen. Genau das ist der nächste Schritt.
Mehr zur Werkstatt hinter dem Blog: die Obsidian-Serie – von der Notiz ins Netz – und die PKM-Serie über das Denken in Notizen.