🧠 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 ruta/a/la/teva/carpeta/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:

   Bash

   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.

L’Il·lusionisme del Symlink (Error 404 a Cloudflare)

• 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.