Dinuxnode Brain

Come ho Costruito il mio Digital Garden Statico (Quartz v5 + Cloudflare + Excalidraw)

3 minuti

Executive Summary

Un Second Brain deve essere veloce, leggero e fruibile ovunque senza attriti.
Ho scoperto Quartz v5 che compila il repo/vault Obsidian e lo serve sull’Edge CDN globale di Cloudflare. Per risolvere il rendering dei diagrammi vettoriali Excalidraw in light/dark mode ho sviluppato e pubblicato un plugin open-source ad-hoc: quartz-excalidraw.

L’Architettura: Da Obsidian all’Edge Cloudflare

L’obiettivo era semplice: continuare a scrivere in Markdown locale su Obsidian, fare git push, e lasciare che il cloud compili e distribuisca tutto in pochi secondi a costo zero.

static-site-simple-flowstatic-site-simple-flow

Lo Stack Tecnologico

  • Authoring: Obsidian nativo, organizzato secondo la tassonomia Johnny.Decimal a 7 pilastri.
  • Privacy Selettiva: Plugin Quartz @quartz-community/explicit-publish. Solo le note con publish: true nel frontmatter YAML vengono compilate ed esposte; l’intero resto del vault rimane privato e non pubblicato.
  • Static Site Engine: Quartz v5, configurato in quartz.config.yaml con supporto esteso a wikilink ([[...]]), callout nativi, rendering KaTeX per la didattica matematica e mappe concettuali interattive (Graph View e Explorer).
  • Deployment & Edge: Cloudflare Pages / Workers via Wrangler, con build automatica su push GitHub e distribuzione globale distribuita su oltre 300 data center a latenza millisecondi.

L’Ostacolo Excalidraw e la Nascita del Plugin

Nel vault uso diagrammi Excalidraw per tutto quello che mi passa per la testa, architetture, flussi hardware e schemi concettuali. In Obsidian, incorporo i diagrammi con la classica sintassi wikilink:

<div class="excalidraw-svg-container"><img class="excalidraw-svg-light" src="/img/static-site-simple-flow.excalidraw.light.svg" alt="static-site-simple-flow" loading="lazy" /><img class="excalidraw-svg-dark" src="/img/static-site-simple-flow.excalidraw.dark.svg" alt="static-site-simple-flow" loading="lazy" /></div>
<div class="excalidraw-svg-container" style="max-width: 800px;"><img class="excalidraw-svg-light" src="/img/custom-llama-cpp.excalidraw.light.svg" alt="800" loading="lazy" /><img class="excalidraw-svg-dark" src="/img/custom-llama-cpp.excalidraw.dark.svg" alt="800" loading="lazy" /></div>

Il “Muro” in Quartz

Quartz di default non supporta nativamente l’embed diretto dei file .excalidraw o .excalidraw.md nel corpo delle pagine:

  • I viewer Canvas o le soluzioni esistenti risultavano pesanti, non responsive o tentavano di renderizzare canvas interattivi separati invece di illustrazioni pulite.
  • Ho abilitato l’auto-export SVG di Obsidian Excalidraw, per generare due file vettoriali separati:
    • disegno.excalidraw.light.svg
    • disegno.excalidraw.dark.svg
  • Però avrei dovuto linkarli a mano nel MD, perdendo la capacità di editarli velocemente e di gestire light/dark. Quartz non sapeva come risolvere il link originale ![[disegno.excalidraw]] verso i due SVG e non gestiva il toggle dinamico del tema chiaro/scuro.

La Soluzione: quartz-excalidraw

Per non dover cambiare manualmente centinaia di link nelle note o sporcare il Markdown con codice HTML o CSS proprietario, ho chiesto alla AI di aiutarmi (nel mio caso Antigravity con Gemini 3.8 flash high e sviluppato/rilasciato una soluzione ad-hoc:

Repository GitHub: https://github.com/dinolupo/quartz-excalidraw

Come Funziona il Plugin

  1. Zero modifiche al Markdown: Nelle note continui a scrivere normali wikilink ![[mio-schema.excalidraw]] o sintassi Markdown ![Alt](mio-schema.excalidraw).
  2. Trasformazione in-memory all’AST: Il transformer aggancia la fase textTransform del compilatore Quartz: intercetta i pattern Excalidraw e sonda la presenza dei file SVG esportati (sia nella directory locale della nota che nella cartella centralizzata img/).
  3. Switch Automatico Light/Dark Mode: Genera un contenitore semantico HTML contenente entrambi i riferimenti SVG: 
    <div class="excalidraw-svg-container" style="max-width: 800px;">
  <img class="excalidraw-svg-light" src="/img/schema.excalidraw.light.svg" loading="lazy" />
  <img class="excalidraw-svg-dark" src="/img/schema.excalidraw.dark.svg" loading="lazy" />
</div>
  4. CSS Reattivo Integrato: Tramite externalResources(), inietta le regole CSS agganciate ai selettori Quartz (:root[saved-theme="dark"] e body.theme-dark), garantendo che:
    • In modalità chiara sia visibile solo la versione light.
    • Al cambio tema, il diagramma passi istantaneamente e senza ricaricare la pagina alla versione scura ad alto contrasto.
    • La grafica vettoriale rimanga nitida e zoomabile su qualsiasi display Retina senza sgranare.

Vista grafico

Link entranti