←
EN
DevOps / Workflow

Dal CMS fallito all'architettura perfetta: Come gestisco il mio blog e la Study Board con Obsidian, Astro e Git

Il racconto del mio viaggio tecnico: dalle trappole di Decap e Keystatic alla scoperta del workflow definitivo con Obsidian, Git e Astro, per scrivere da PC e mobile in totale indipendenza.

Quando ho progettato la nuova versione del mio portfolio personale e della Study Board, avevo un obiettivo chiaro in mente: volevo uno strumento agile che mi permettesse di pubblicare articoli e prendere appunti di studio in qualsiasi momento, sia mentre lavoro dal mio PC con Linux Mint, sia mentre sono in mobilità con l’iPad.

In oltre 20 anni di ingegneria software ho imparato che le soluzioni più semplici sono spesso le più solide. Tuttavia, trovare il giusto equilibrio tra un sito statico ultra-veloce sviluppato in Astro e un sistema di gestione contenuti (CMS) davvero usabile da mobile si è rivelato un percorso pieno di ostacoli e preziose lezioni architetturali.

In questo articolo racconto le trappole in cui sono caduto, i bug riscontrati e come sono arrivato alla mia architettura definitiva: zero CMS esterni, zero abbonamenti SaaS e il 100% del controllo nei file Markdown.

1. Il tentativo con Decap CMS (e la trappola del mobile)

La mia prima scelta è stata Decap CMS (l’ex Netlify CMS). L’idea iniziale sembrava attraente: un pannello web integrato nella rotta /admin del sito che salvava i file Markdown direttamente su GitHub.

Purtroppo mi sono scontrato subito con un limite strutturale: Decap CMS è stato progettato nel 2016 per schermi desktop. I suoi componenti React basati su layout rigidi a due colonne (SplitPane) soffrono terribilmente su smartphone e tablet. Tentare di forzare il CSS con regole responsive ha solo evidenziato il problema principale: stavo combattendo contro un’architettura nata per il desktop.

2. Il tentativo con Keystatic (e il bug delle Serverless Functions)

Sono passato quindi a Keystatic, uno strumento moderno dell’ecosistema Astro con un’interfaccia elegante. In locale funzionava a meraviglia, ma non appena ho pubblicato il sito su Netlify è emerso un problema architetturale insidioso.

In ambiente di produzione serverless su Netlify, durante il callback di autenticazione con GitHub (/api/keystatic/github/oauth/callback), l’infrastruttura di gestione dei cookie di stato OAuth generava un errore HTTP 500 (Authorization failed). La ragione? Un’incompatibilità tra la gestione dei cookie di sessione delle Serverless Functions di Netlify e le rotte dinamiche di Astro v5 in modalità statica.

La soluzione proposta era utilizzare un servizio cloud terzo (Keystatic Cloud) per far da ponte all’autenticazione. Ma questo violava uno dei miei principi fondamentali: non volevo alcuna dipendenza da servizi SaaS di terze parti per gestire i miei dati.

3. La svolta: Perché usare un CMS web quando abbiamo già Git?

A quel punto mi sono fatto la domanda che ogni ingegnere dovrebbe porsi: perché sto cercando di far girare un’applicazione di gestione contenuti dentro un browser web quando ho già un repository Git pieno di file Markdown e un’applicazione nativa eccezionale sul telefono?

La risposta è stata passare a Obsidian accoppiato a Git.

4. L’Architettura Definitiva: Obsidian + Astro + Git

L’idea è di una semplicità disarmante:

  1. Il repository Git come unica sorgente di verità: Tutti i miei articoli e le schede della Study Board risiedono in src/content/ come file .md con frontmatter YAML.
  2. Obsidian come editor nativo su PC e iPad: Apro il repository in Obsidian.
  3. Pura compilazione statica con Astro: Il sito Astro rimane un generatore di pagine statiche (SSG) puro al 100%, senza codice di CMS o pacchetti React inutili.

L’organizzazione del Vault in Obsidian

Per evitare che la barra laterale di Obsidian fosse intasata dal codice sorgente di Astro (components, pages, layouts, node_modules), ho utilizzato la funzione nativa “Excluded files” di Obsidian nascondendo le cartelle del codice.

Sia su PC che su iPad la mia sidebar mostra esclusivamente le cartelle dei contenuti:

  • 📁 studyboard
  • 📁 blog
  • 📁 projects
  • 📁 _templates

5. Il Sistema dei Template e i Metadati YAML

In Obsidian ho creato una cartella src/content/_templates/ contenente le schede tipo per la Study Board, il Blog e i Progetti. Il prefisso _ garantisce che i loader di Astro ignorino la cartella durante la build del sito.

Dall’iPad o dal PC mi basta un tocco per inserire il modello desiderato. Sfruttando la funzionalità Properties di Obsidian, posso gestire i metadati YAML (Stato, Categoria, Tag, Emoji) con selettori visuali, date pre-compilate e pillole colorate.

6. Sincronizzazione Mobile Nativa e CI/CD

Su iPad ho installato il plugin della community Git (di Vinzent03) autenticato con un mio GitHub Personal Access Token.

Il flusso di lavoro quotidiano è diventato incredibilmente fluido:

  1. Scrivo o aggiorno una scheda su iPad o PC (anche offline).
  2. Obsidian Git esegue il commit e push automatico su GitHub.
  3. Netlify rileva il push e compila il sito aggiornato in circa 30 secondi.

Su Linux Mint ho salvato le credenziali nel credential helper di Git (git config --global credential.helper store), eliminando per sempre la richiesta di password.

Conclusioni

Avere un sito web veloce non significa solo ottimizzare il codice di frontend, ma costruire una Developer Experience soddisfacente e priva di attriti.

Sbarazzarmi dei CMS web tradizionali mi ha permesso di:

  • Eliminare qualsiasi dipendenza da piattaforme SaaS terze.
  • Mantenere la codebase del sito Astro pulita e velocissima.
  • Guadagnare un’esperienza di scrittura nativa, offline-first e piacevole da tutti i miei dispositivi. Modifica da iPad