Platylog

Obsidian, Quartz und Codeberg

5 min read

  • Obsidian ist im Kern ein Markdown-Editor, der durch seine zahlreichen Funktionen, Plugins und Themes zu einem der vielseitigsten Tools überhaupt gehört.
  • Quartz ist ein Static Site Generator, der auf Obsidian spezialisiert ist und dort verfasste Inhalte in eine eigene Website umwandeln kann (die Website, auf der dies gerade zu lesen ist, ist eine davon).
  • Codeberg ist ein Git-basierte, nicht-kommerzielle Entwicklungsplattform aus Berlin.

Quartz wurde ursprünglich für die Nutzung mit Github bzw. Github pages entwickelt, unterstützt aber auch andere Hosting-Lösungen. Eine Anleitung und Skripte für Codeberg sind aber leider noch nicht vorhanden. Dadurch fallen bei der Nutzung von Codeberg einige integrierte “Annehmlichkeiten” der Software weg. Einige Vorzüge von Github (wie die Kommentarfunktion per giscus/utterances) sind afaik aktuell gar nicht nutzbar. Es ist jedoch relativ leicht eine statische Website oder einen Blog lokal auf dem Rechner zu erstellen und dann in ein Repository auf Codeberg hochzuladen. Mittels Codeberg Pages sind die Inhalte des Repository dann wie eine normale Website unter https://<username>.codeberg.page abrufbar.

Ich interessiere mich zwar für Technik und Software, habe aber nur oberflächliche Kenntnisse, wie der ganze Kram genau funktioniert. Trotzdem habe ich es mit der Dokumentation und einigen Versuchen hinbekommen, diese Website zu bauen und zu veröffentlichen.

Installation und Einrichtung unter Linux

Zur Nutzung habe ich Obsidian als Editor installiert, die Installationspakete sind auf der Website bzw. im Paketmanager zu finden.

Es ist natürlich auch jeder andere Texteditor möglich, Quartz unterstützt jedoch das angepasste Markdown von Obsidian und liefert daher sehr gute Ergebnisse.

Quartz ist vereinfacht gesagt dafür zuständig, die Dateien in html umzuwandeln, mit Styles zu versehen und in Form einer Website zu pressen. Dafür müssen node (>v20), npm (>v9.3.1) und git über den Paketmanager der Wahl installiert werden. Die von Quartz erstellten Dateien werden mittels git in ein lokales Repository gepackt, welche dann zu einem entfernten Repository, in diesem Fall zu Codeberg, hochgeladen werden.

Installation

  1. Verzeichnis erstellen, in welchem Quartz installiert werden soll und in einem Terminal öffnen.
  2. Das Repository von Quartz mit git herunterladen:
git clone https://github.com/jackyzha0/quartz.git
  1. In das Verzeichnis wechseln und die Pakete installieren:
cd quartz
npm i
npx quartz create
  1. Quartz fragt bei der Erstkonfiguration nach einigen Optionen, die nach Bedarf ausgewählt werden können.

Konfiguration von Quartz

→ https://quartz.jzhao.xyz/configuration

Inhalte erstellen

In Obsidian das Unterverzeichnis “content” im Installationsort von Quartz als neuen Vault wählen. Die Datei “index” darf nicht gelöscht werden (kann aber bearbeitet werden), da sie sozusagen die landing page der Website ist. Im Ordner und Unterordnern können nun einzelne Artikel oder Posts erstellt werden. Standardmäßig werden die Ordner “.obsidian”, “templates” und “private” von Quartz ignoriert (siehe Konfiguration von Quartz).

Website bauen

Im “quartz”-Verzeichnis kann mittels npx quartz build --serve die Website gebaut und auf einem lokalen Webserver unter localhost:8080 im Browser angezeigt werden. Hier kann überprüft werden, wie die Website aussieht. Beim bauen der Website wird diese in das Unterverzeichnis “public” gespeichert, in welchem die fertig umgewandelten Dateien abgespeichert werden.

Website auf Codeberg hosten

Das Verzeichnis “public” wird nun als lokales Repository genutzt, welches per git zu Codeberg hochgeladen wird. Dazu wird zuerst ein neues Repository auf der Plattform benötigt:

  1. Auf Codeberg ein neues Repository mit dem Namen pages erstellen. Der Name ist nicht veränderbar, da das Repository von der Plattform automatisch als Codeberg Pages behandelt wird.
  2. In den Einstellungen von Codeberg unter Applications ein Access-Token mit der Berechtigung “Repository: Read and Write” erstellen und gut abspeichern. Dieses Token wird in Kombination mit der E-Mail-Adresse zum Login benötigt, wenn auf das entfernte Repository per git zugegriffen wird.
  3. Im Terminal in das Unterverzeichnis “public” im Installationsort von Quartz wechseln.
  4. Ordner als lokales Repository erstellen und in den main-Zweig wechseln:
git init
git checkout -b main
  1. Entferntes Repository (Codeberg Pages) hinzufügen:
git remote set-url origin <DIE URL DES CODEBERG-REPOSITORY>

Workflow

Nachdem alles eingerichtet ist, sieht der Workflow wie folgt aus…

  1. Beiträge als Markdown-Dateien im Obsidian-Vault erstellen.
  2. Quartz die Website generieren lassen:
npx quartz build
  1. Die erstellte Website im Unterverzeichnis “public” mittels git auf Codeberg hochladen:
git status
git add .
git commit -m "Kommentar"
git push origin main    // Die Dateien von main (lokal) zu origin (entfernt) pushen
username: <login>    // E-Mail-Adresse/Login
password: <secret-token>     // Das generierte Access-Token
  1. Da Codeberg Pages die Index.html-Datei im Hauptverzeichnis erkennt, ist die Website unter https://<username>.codeberg.page aufrufbar.

Automatisierung

Die ganzen Befehle händisch einzugeben oder nacheinander zu kopieren, ist zugegebenermaßen etwas nervig. Daher habe ich ein bash-script erstellt, welches die Befehle einzeln abarbeitet und nach Benutzername und Passwort-Token fragt. Sollte ein Befehl fehlschlagen, wird der Vorgang abgebrochen.

Achtung

Das Skript ist darauf ausgelegt, dass es im Verzeichnis über dem “quartz”-Verzeichnis liegt. Falls eure Ordner-Struktur also anders aussieht, wird es nicht funktionieren oder könnte sogar Schaden an Dateien anrichten.

Das Skript also nicht einfach kopieren, sondern für eure Zwecke anpassen!

  1. Folgenden Inhalt in eine leere bash-Datei (<scriptname>.sh) einfügen:
#!/bin/bash -e
 
cd quartz
echo "Baue Quartz..."
npx quartz build
echo "Quartz wurde gebaut!"
cd public
git status
git add .
echo "Die Änderungen wurden erfolgreich zum Commit vorgeschlagen"
echo -n "Änderungen kommentieren: "
read name
git commit -m "$name"
echo "Quartz wird hochgeladen..."
git push origin main
echo "Quartz auf Codeberg veröffentlicht!"
  1. Die Datei mittels chmod +x <scriptname>.sh ausführbar machen.
  2. Im Terminal mit ./<scriptname>.sh starten.

Backlinks