Se ti piace già scrivere in Notion ma il tuo sito è costruito con Astro o un altro stack statico file-first, rimane una piccola lacuna nel workflow che diventa fastidiosa più in fretta del previsto.

Scrivere la bozza in Notion è fluido. Spostare sezioni è facile, le immagini sono facili da gestire e la pagina rimane leggibile mentre il pezzo sta ancora prendendo forma. Poi arriva la pubblicazione e, all’improvviso, sei di nuovo nel repository a copiare contenuti, correggere il frontmatter, generare una versione inglese, eseguire il build, fare push e aspettare il deployment. La prima metà sembra scrittura. La seconda sembra manutenzione.

Era esattamente il gap che volevo eliminare. Volevo mantenere Notion come superficie di scrittura, ma non volevo trasformare di nuovo il blog Astro in un sistema di contenuti pesante lato backend. Sono quindi arrivato a una pipeline stretta: scrivere l’articolo in Notion, lasciare che GitHub Actions recuperi la pagina, convertirla in file Markdown nel repository, generare versione inglese e slug, eseguire la validazione del build e poi continuare nel flusso di deploy di produzione già esistente.

Se il tuo blog non è ancora passato a un setup file-first, Astro vs WordPress: perché preferisco Markdown e GitHub Actions per un blog da sviluppatore è un punto di partenza migliore. Se pubblichi già direttamente da Markdown nel repository, Scrivere Markdown in locale e fare deploy con git push: il mio workflow bilingue copre quel lato. Questo articolo sta nel mezzo: mantenere la comodità di scrittura di Notion senza rinunciare alla struttura e alla disciplina di release di un repository di contenuti Astro.

Il mio primo istinto è stato lo stesso di molti: renderlo subito event-driven. Pubblicare in Notion, inviare un webhook, triggerare un Worker, scrivere i file, fare deploy in produzione. Sulla carta sembra più pulito. Ma più mappavo i reali percorsi di errore, più facevo un passo indietro. Per un blog personale, la cosa più importante nella prima versione non è la velocità, ma la facilità di debugging. Così ho mantenuto intenzionalmente semplice la prima versione. Il body dell’articolo vive nel contenuto della pagina Notion; le properties contengono solo metadata come titolo, summary, categoria, tag, slug e stato; ogni run elabora una pagina alla volta; la regola di queue predefinita è publish = true più status = Ready; e aggiornare un post esistente richiede di riutilizzare lo slug originale e abilitare esplicitamente gli update.

Niente di questo sembra impressionante, ma rende la pipeline facile da capire. Se una pagina non entra mai nella queue, probabilmente i metadata sono sbagliati. Se fallisce la generazione inglese, quello è un livello separato. Se fallisce il build, torna al content schema. Se il deployment non parte, guarda il workflow successivo. Preferisco una prima versione più lenta ma ovvia da diagnosticare rispetto a un sistema “real-time” che diventa fastidioso al primo errore.

Questo compromesso ha ancora più senso per un blog individuale. Un team potrebbe preoccuparsi di pubblicazione immediata, stati di review multi-editor e workflow event più ricchi. A me interessa qualcosa di più semplice: se finisco un articolo di sera, posso averlo online la mattina seguente senza rischiare sovrascritture accidentali? Il polling non è glamour, ma per questo lavoro è difficile odiarlo.

Tolti i nomi degli strumenti, il workflow è lineare:

Notion page body
  -> mark page as Ready + publish
  -> GitHub Actions pulls markdown
  -> generate English title, description, body, and slug
  -> write files into src/content/posts/zh-cn and en-us
  -> run build validation
  -> push to main
  -> trigger the production deploy workflow
  -> write status, links, and commit SHA back to Notion

Le due cose a cui tenevo di più erano queste. Primo, Notion è soltanto la superficie di scrittura, non l’artefatto pubblicato finale. Il sito live continua a essere generato da file Markdown nel repository. Secondo, l’automazione non deve costare la protezione contro sovrascritture accidentali. Per questo il repository mantiene una struttura di contenuti molto semplice:

src/content/posts/
├── zh-cn/
│   └── notion-to-astro-auto-publish-workflow.md
└── en-us/
    └── notion-to-astro-auto-publish-workflow.md

Entrambe le versioni linguistiche condividono lo stesso path, mantenendo puliti routing e aggregazione Astro. Anche sul lato Notion gli input richiesti rimangono limitati: titolo, summary, categoria, tag, slug, publish state, queue state, auto-translate e flag esplicito di update. Il body rimane nel contenuto della pagina, non in una property. Sembra ovvio, ma conta. Lo script recupera Markdown esportato dalla pagina. Non ricostruisce l’articolo attraversando manualmente i blocchi e indovinando come serializzarli. Finché la pagina può essere esportata correttamente da Notion, può diventare un normale file di contenuto senza molta cerimonia aggiuntiva.

Se la domanda più pratica è “come dovrei scrivere dentro Notion affinché l’articolo venga sincronizzato bene con un blog statico?”, oggi la mia risposta è semplice: tratta Notion come un editor Markdown comodo, non come un playground di layout visuale. Quindi livelli heading normali, paragrafi normali, code block fenced per comandi e config, immagini vicine al paragrafo a cui appartengono e righe separate per link o video che potresti voler migliorare in seguito. Più dipendi da trucchi di presentazione esclusivi di Notion — bookmark visuali pesanti, layout multi-colonna o blocchi troppo decorativi — più lavoro di pulizia avrai dopo l’export.

Per me funziona meglio una struttura molto semplice. Apri con una sezione guidata dal problema. Porta avanti la spiegazione principale con alcuni paragrafi lunghi. Inserisci code block quando comandi o configurazione contano davvero. Mantieni le immagini accanto al paragrafo pertinente invece di trattarle come una gallery. Se un link di riferimento o un video è importante, dagli una riga propria. A quel punto la pagina Notion si comporta già molto come un file sorgente Markdown pulito, ed è esattamente per questo che la sincronizzazione diventa affidabile.

Il pattern più conservativo assomiglia a questo:

# Title

Open with two or three paragraphs that explain the problem and the decision.

## One key section

Keep writing.

```bash
pnpm build
node scripts/notion-auto-publish.mjs process
```

Then add pitfalls, limits, or recovery notes.

https://example.com/some-reference

Quando scrivi in questo modo, il passaggio di sync smette di sembrare “converti una pagina Notion sofisticata in un blog” e inizia a sembrare “prendi una bozza sorgente pulita da Notion e inseriscila nel repository”. Questo cambio di mentalità conta molto.

Come è diviso lo script: tre comandi, tre lavori

Anche gli entrypoint dello script restano stretti:

node scripts/notion-auto-publish.mjs process
node scripts/notion-auto-publish.mjs finalize-success
node scripts/notion-auto-publish.mjs finalize-failure

process svolge il lavoro reale. Seleziona una pagina idonea, recupera il body, genera il lato inglese, scrive entrambi i file Markdown e poi lascia continuare la catena di build e release. I callback di successo e fallimento gestiscono soltanto il write-back su Notion. Preferisco questa separazione perché mantiene ogni fase onesta. Non diventa un unico script enorme che prova contemporaneamente a interrogare Notion, tradurre contenuti, validare il build, fare push Git e aggiornare gli stati.

Più ho usato il sistema, meno mi interessava il passaggio di traduzione in sé e più mi interessava la protezione dello slug. Quando la pubblicazione diventa automatica, il rischio più grande di solito non è “ho cliccato un pulsante di troppo”. È “pensavo di pubblicare un nuovo post, ma il sistema credeva che volessi sostituirne uno vecchio”. Con titoli simili e slug generati automaticamente, il rischio diventa concreto.

Per questo la regola è volutamente rigida. I nuovi post dovrebbero idealmente ricevere uno slug unico. Se il repository contiene già quello slug, il processo fallisce per default. La sostituzione è consentita soltanto quando il permesso di update viene abilitato esplicitamente. La pipeline è conservativa di proposito: preferisce fermarsi e lamentarsi invece di indovinare silenziosamente che intendessi sovrascrivere qualcosa. Per un blog penso sia il bias corretto. Recuperare una pubblicazione mancata è facile. Recuperare da una sostituzione accidentale è di solito più fastidioso.

Un altro elemento che ha influenzato il setup è stato il comportamento dei gateway OpenAI-compatible. Ho già incontrato casi strani: una risposta 200 OK senza body utile, una risposta non-streaming vuota mentre lo streaming funzionava o uno schema apparentemente accettato che restituiva comunque i campi sbagliati. Per questo il livello di traduzione ha più fallback. Non perché volessi uno script intelligente, ma perché una volta che generazione inglese e generazione slug vivono nel percorso di pubblicazione, quel livello non può essere fragile. Non tratto il modello come un publisher magico. Lo considero un passaggio di trasformazione sostituibile dentro un sistema più ampio. Può aiutare a produrre bozza inglese, titolo e description, ma i confini rigidi restano nel repository: content schema, build validation e protezione dalle sovrascritture.

I confini che contano

Dopo aver usato davvero questa pipeline, non penso che le parti pericolose vivano nel body dell’articolo. Vivono nei confini. Pensi di aggiornare un vecchio post ma hai cambiato lo slug. Pensi che le page properties contengano il body, ma lo script non le legge per quello. Presumi che Published significhi deployment completamente verificato, mentre in questa versione significa davvero che la content pipeline ha raggiunto con successo il trigger del deploy di produzione. Oppure pensi che l’automazione elimini il bisogno di test manuali, ma i fallimenti di build devono ancora essere diagnosticati nel repository.

C’è anche un altro fraintendimento comune. Le persone sentono “scrivi in Notion e pubblica automaticamente sul blog” e presumono che si possa formattare la pagina in qualsiasi modo e affidarsi alla pipeline per trasformarla magicamente in un post pulito. Non la vedo più così. In questo setup Notion agisce davvero come una superficie di authoring Markdown più comoda. Da quando ho iniziato a trattarlo in questo modo, tutto il workflow è migliorato. Ho smesso di preoccuparmi che ogni blocco fosse bello dentro Notion e ho iniziato a preoccuparmi di più che la struttura degli heading fosse pulita, i code fence corretti, le immagini nelle posizioni giuste e i link importanti su righe proprie.

Per questo continuo a preferire un percorso di debug conservativo. Se devo testare una pagina, eseguo il workflow manualmente, passo un page_id specifico e tengo dry_run attivo al primo giro. In questo modo la pagina Notion viene comunque recuperata, il lato inglese viene generato, l’output temporaneo viene scritto e il build viene validato, ma non viene fatto push e la produzione non cambia. È molto più facile fidarsi dell’automazione dopo averla vista attraversare i livelli intermedi rischiosi.

Se dovessi ridurre le regole operative a un insieme molto piccolo, sarebbero queste: scrivi il body nel contenuto della pagina Notion, non nelle properties; assegna quando possibile uno slug proprio ai nuovi post; riutilizza lo slug originale e abilita esplicitamente gli update quando modifichi un post esistente; porta prima la sorgente cinese a uno stato pubblicabile e poi lascia che l’automazione generi l’inglese; e quando un run fallisce, non fissarti sull’ultimo exit 1: trova il primo passaggio che si è davvero rotto.

È questo il motivo per cui ho scelto questo design. Non è l’architettura di blog più ambiziosa del mondo. È semplicemente una linea pulita tra tre cose che volevo mantenere: Notion come superficie di scrittura, Astro come target di pubblicazione file-first e GitHub Actions come livello che assorbe il lavoro ripetitivo in mezzo.

Per me è molto più utile che aggiungere un altro pulsante admin.