Marktmannen wiki Personal Knowledge Management (PKM)

Obsidian-vault publiceren met Quartz

Laatst bijgewerkt

TL;DR: Quartz is een gratis, open-source static site generator (winnaar in de categorie "Tools" van Obsidians Gems of the Year 2023, inmiddels op versie 5) waarmee je een Obsidian-vault als website publiceert — meestal op GitHub Pages — als alternatief voor het betaalde Obsidian Publish; het grootste aandachtspunt is het filteren van privécontent vóór publicatie.

Publiceren van Markdown-notities bestaat uit drie componenten: (1) de editor die Markdown maakt (Obsidian), (2) de static site generator die Markdown naar HTML omzet (Quartz), en (3) de hosting (GitHub Pages, Cloudflare of Netlify). Obsidian Publish doet alle drie voor $8 per site per maand bij jaarbetaling ($10 bij maandbetaling); Quartz vervangt alleen de middelste stap maar is gratis, zelf te hosten en veel verder aan te passen — inclusief wikilinks, backlinks en de bekende graph view.

Wanneer Quartz i.p.v. Obsidian Publish

  • Publish: makkelijkst, zit ín Obsidian, met eigen CSS/JS, eigen domein en wachtwoordbeveiliging, maar betaald en niet zelf te hosten; volgens Van der Hoeven traag en zonder automatiseringspipeline.
  • Quartz: gratis, open source, goed gedocumenteerd, past in een CI/CD-pipeline (GitHub Actions), maar vereist comfort met terminal, Git/GitHub en Node/npm.
  • Van der Hoeven gebruikt bewust beide naast elkaar: Publish voor haar hoofdvault, Quartz voor losse publieke projecten — beste tool per use case.

Standaardroute (Quartz 5; Van der Hoeven deed dit nog met Quartz 4)

Quartz 5 is de actuele versie (productie-branch v5, met een eigen migratiepagina vanaf Quartz 4) en vraagt Node v22+ en npm v10.9.2+. 1. Quartz-repo clonen, npm i, npx quartz create (keuze: lege vault, kopie of symlink van bestaande map), en de plugins installeren met npx quartz plugin install --from-config. 2. Nieuwe GitHub-repo aanmaken en als origin koppelen (Quartz zelf blijft upstream); syncen met npx quartz sync. 3. Dezelfde map als Obsidian-vault openen; content in de content/-map schrijven, eventueel met Templater-templates in het door Quartz verwachte frontmatter-formaat (title, draft, tags). 4. Lokaal previewen met npx quartz build --serve (localhost:8080). 5. Hosten op GitHub Pages: deploy.yml GitHub Action toevoegen (in de docs-versie draait die op branch v5, met plugin install vóór de build), in repo-settings Pages op "GitHub Actions" zetten; site staat op gebruikersnaam.github.io/reponaam. 6. Optioneel eigen domein: voor een apex-domein vier A-records naar GitHubs IP-adressen (185.199.108.153 t/m 185.199.111.153), voor een subdomein een CNAME naar <gebruikersnaam>.github.io; daarna custom domain in Pages-settings. HTTPS afdwingen noemt Van der Hoeven; de Quartz-docs behandelen het niet.

Privécontent-route (Boswell, oudere Hugo-gebaseerde Quartz)

Boswell wilde absoluut geen privénotities online en bouwde daarom een lokale pre-compile-pipeline in plaats van Quartz' eigen GitHub Action: obsidian-export (Rust) filtert de vault op basis van een .export-ignore-bestand in de vault-root (mappen als private/*, people/*, 1-1/*, .obsidian/*) en zet Obsidian-wikilinks om naar standaard Markdown; daarna bouwt hugo-obsidian + Hugo de site, en alleen de gecompileerde public/-map gaat naar GitHub Pages. Kernprincipe: filter privébestanden zo vroeg mogelijk in de pipeline, zodat ze nooit in de geparste map (laat staan de repo) terechtkomen. Let op: Boswell beschrijft een oudere, volgens hem Hugo-gebaseerde Quartz-opzet; de actuele Quartz (route hierboven) is een standalone Node-tool en filtert inmiddels zelf (zie hieronder).

Native selectieve publicatie (Quartz 5)

Quartz kan privécontent zelf weglaten: RemoveDrafts (standaard aan, notities met draft: true), ExplicitPublish (alleen notities met publish: true) en ignorePatterns in de config. Daarmee is een aparte obsidian-export-voorbewerking niet meer nodig. Waarschuwing: de filters gelden alleen voor Markdown — alle niet-Markdown-bestanden (afbeeldingen, PDF's e.d.) in de content-map worden altijd openbaar.

Relevantie voor eigen kennisbank

Dit is de publicatielaag bovenop een Zelfverbeterende Kennisbank: de wiki-map is al Markdown met wikilinks, dus een static site generator als Quartz kan die direct als digital garden serveren. Het .export-ignore-principe (whitelist/blacklist vóór de build) is het spiegelbeeld van de cockpit-regel om klantdata nooit mee te publiceren.

Open vragen

  • Hoe verhoudt Quartz zich tot een buildless conversie-aanpak (geen Node-toolchain, direct HTML genereren) voor een wiki die achter toegangsbeheer (bv. Cloudflare Access) staat?

Verwante concepten

Bronnen

#kennisbank

Backlinks