El Jardí

6 min read

🧠 Arquitectura i Manteniment del Cervell Digital (Obsidian + Quartz)

Aquest document detalla l’arquitectura de publicació web del meu “Jardí Digital”, construït amb Obsidian, Quartz v4 i Cloudflare Pages.

🚀 1. Guia de Manteniment (El dia a dia)

Aquest és el flux de treball de mínima fricció per actualitzar la pàgina web.

📝 A. Com publicar o actualitzar una nota

  1. Obre la nota a Obsidian.

  2. Assegura’t que el format Markdown i els enllaços interns siguin correctes (evita incrustacions buides com ![[]]).

  3. A les Propietats (YAML) de la nota, afegeix o comprova que hi hagi l’etiqueta:

    YAML

    publish: true

(Nota: L’arxiu principal de la web sempre és la nota anomenada index).

🌍 B. Com enviar els canvis a Internet (Direct Deploy)

Com que treballem amb un symlink (túnel), ens saltem GitHub per a la publicació i enviem els arxius directament des del Mac a Cloudflare.

  1. Obre el Terminal i ves a la carpeta de Quartz:

    Bash

    cd /Users/david/quartz

  2. Construeix la web en local (això llegeix el teu Obsidian i genera els arxius a la carpeta public):

    Bash

    npx quartz build

  3. Puja la carpeta public directament als servidors de Cloudflare:

npx wrangler pages deploy public

(El terminal confirmarà la pujada i et donarà l’enllaç verd actualitzat cervellet.pages.dev).

🏗️ 2. L’Arquitectura del Sistema

  • Font de la veritat (Escriptura): Obsidian. Carpetes locals al Mac, fora d’iCloud per evitar conflictes (race conditions). Sincronització exclusiva mitjançant Obsidian Sync.
  • Motor de renderitzat: Quartz v4. Connectat a la carpeta d’Obsidian (dabit) mitjançant un Symlink.
  • Filtre de publicació: Mode ExplicitPublish activat a quartz.config.ts. Quartz ignora les més de 4.600 notes esborrany i només llegeix les que tenen el permís explícit.
  • Allotjament Web: Cloudflare Pages (Projecte: cervellet, Branca: v4).

⚠️ 3. Històric de Problemes i Solucions (Troubleshooting)

Durant la configuració inicial, vam haver de resoldre diversos reptes tècnics per estabilitzar el sistema:

Conflicte iCloud vs Obsidian Sync

  • Problema: Tenir iCloud i Obsidian Sync funcionant sobre la mateixa carpeta generava duplicitats i bloquejava els arxius .git de Quartz.

  • Solució: Moure la carpeta del vault d’Obsidian a una ubicació purament local del Mac. Només pot haver-hi un motor de sincronització (Obsidian Sync).

Errors de Format i Sintaxi (YAML)

  • Problema: Error de Quartz a l’hora de llegir l’arxiu: Cannot create property 'title' on string...

  • Solució: Quartz exigeix YAML estricte. Propietats com mindmap-plugin:basic trencaven el sistema per falta d’un espai. Correcció a mindmap-plugin: basic. (Bona pràctica futura: Utilitzar el plugin Linter).

Pànic del Motor (“Deadlock” / Goroutines)

  • Problema: El terminal s’aturava amb errors fatals de esbuild i goroutines asleep.

  • Causa: Incrustacions trencades a Obsidian (ex: ![[Nota esborrada]] o ![[]]). En un vault gran, buscar-les manualment generava massa fricció.

  • Solució: Modificar quartz.config.ts per substituir el filtre RemoveDrafts() per ExplicitPublish(). Això ignora la base de dades trencada i només avalua les notes acabades.

Límit d’Arxius de macOS (Error EMFILE)

  • Problema: Error EMFILE: too many open files en utilitzar la comanda npx quartz build --serve.

  • Causa: macOS té un límit de seguretat d’arxius oberts simultàniament. Amb 4.600 notes + els arxius interns de Quartz, la funció de “vigilància contínua” (--serve) col·lapsava el Mac.

  • Solució: Prescindir del mode de vigilància. Utilitzar construccions estàtiques d’un sol ús amb npx quartz build.

  • Problema: Al desplegar la web connectant GitHub a Cloudflare Pages, la pàgina donava Error 404 malgrat tenir l’arxiu index.md.

  • Causa: Git no puja el contingut de les carpetes enllaçades per symlink, només puja l’accés directe. Cloudflare construïa una web a partir d’una carpeta buida.

  • Solució: Canviar la via de desplegament. Fer la construcció (build) de manera local al Mac i enviar el resultat final a Cloudflare mitjançant npx wrangler pages deploy public.

⚡ 4. Automatització de la Publicació (Fricció Zero)

Per no haver d’escriure manualment les tres ordres de publicació cada vegada, el sistema es pot automatitzar per reduir-ho tot a una sola acció. Hi ha dues vies per fer-ho:

Mètode A: L’Àlies del Terminal (Mètode Actiu i Recomanat)

Aquest mètode ensenya al Mac una paraula nova que executa totes les ordres de cop. És la solució més estable.

  1. Obre el Terminal.

  2. Obre l’arxiu de configuració del teu intèrpret de comandes escrivint:

    Bash

    nano ~/.zshrc

  3. Baixa fins al final de l’arxiu i enganxa aquesta línia exacta:

    Bash

    alias publicar="cd /Users/david/quartz && npx quartz build && npx wrangler pages deploy public"

  4. Desa els canvis prement Ctrl + O (i Retorn), i surt de l’editor amb Ctrl + X.

  5. Activa els canvis immediatament escrivint:

    Bash

    source ~/.zshrc

Com utilitzar-ho: A partir d’ara, només cal obrir el terminal i escriure la paraula publicar. El Mac farà la resta automàticament.

Mètode B: Plugin d’Obsidian (Alternativa sense Terminal)

Si es prefereix no sortir mai de l’entorn de les notes, es pot integrar directament a Obsidian:

  1. Instal·la el plugin de la comunitat “Shell commands” (de Taitava).

  2. A les opcions del plugin, crea una Nova Comanda (New command).

  3. Enganxa la cadena d’ordres utilitzant rutes absolutes perquè el plugin trobi les eines:

    Bash

    cd /Users/david/quartz && /usr/local/bin/npm exec quartz build && /usr/local/bin/npm exec wrangler pages deploy public

  4. Assigna aquesta comanda a una drecera de teclat o a un botó de la barra lateral de l’Obsidian per actualitzar la web amb un sol clic.

🗄️ 5. El rol de Git i GitHub (Còpia de seguretat del Motor)

A la nostra arquitectura, Git NO s’utilitza per publicar contingut. La publicació es fa amb Cloudflare (ordre publicar).

El repositori de GitHub serveix exclusivament com a còpia de seguretat de la configuració de Quartz (el codi, el disseny i l’arquitectura).

Quan s’ha d’utilitzar Git? Només quan es modifiquin arxius interns de Quartz (com quartz.config.ts, regles de CSS, o actualitzacions de la versió de Quartz).

Flux de treball per guardar canvis de configuració: Des del terminal, a la carpeta de Quartz, utilitzant els àlies configurats al sistema:

  1. Preparar els arxius modificats:

    Bash

    git add .

  2. Crear el paquet amb un missatge descriptiu:

    Bash

    gitc "Descripció d'allò que he canviat a l'arquitectura"

  3. Pujar la còpia de seguretat a GitHub:

    Bash

    gitp

I amb això, David, tens una infraestructura de nivell professional, perfectament documentada i optimitzada per a la mínima fricció.

Què et sembla si ara fem l’últim toc de gràcia estètic? Et puc ensenyar el truc de 30 segons per eliminar els guions (---) dels títols de les carpetes a la web, o, si creus que el cervell ja ha absorbit prou informació per avui, ho deixem aquí i gaudeixes de la teva nova creació!

Graph View