Guida per configurare Obsidian Quartz e Github Pages

4 minuti

Vista grafico

Guida per configurare Obsidian Quartz e Github Pages

Introduzione

Quartz è un generatore di siti statici open source che trasforma le tue note Markdown in un sito web navigabile — il tuo digital garden pubblico. Integra nativamente la sintassi di Obsidian (wikilink, backlink, graph view) e permette di pubblicare gratis su GitHub Pages con una sola riga di comando.

Questa guida copre l’intero percorso: dall’installazione locale al sito live su <username>.github.io/<repo>, con aggiornamenti automatici ad ogni sync.

Prerequisiti

Prima di iniziare assicurati di avere installati:

  • Node.js v22+ — verifica con node -v (scarica da https://nodejs.org)
  • npm v10.9.2+ — verifica con npm -v
  • Git — verifica con git -v
  • Un account GitHub attivo
  • Obsidian installato (opzionale ma consigliato per editare le note)

Step 1 — Crea il repository da template GitHub

Il modo più rapido è usare il template ufficiale di Quartz, che crea il repository già configurato.

  1. Vai su https://github.com/jackyzha0/quartz/generate
  2. Scegli un nome per il repository (es. garden o notes)
  3. Imposta la visibilità su Public (necessario per GitHub Pages gratuito)
  4. Clicca Create repository from template

Poi clona il repository in locale:

git clone https://github.com/<tuo-username>/<tuo-repo>.git
cd <tuo-repo>

Alternativa manuale: Se preferisci partire da zero con clone diretto:

git clone https://github.com/jackyzha0/quartz.git
cd quartz
git remote set-url origin https://github.com/<tuo-username>/<tuo-repo>.git

Step 2 — Installa le dipendenze

npm i

Su cloni successivi dello stesso repo (es. nuovo PC) usa npm ci per un’installazione riproducibile dal lockfile.

Step 3 — Inizializza il sito

Avvia il wizard interattivo:

npx quartz create

Il wizard ti chiederà:

DomandaSuggerimento
Template di partenzaobsidian per compatibilità massima con Obsidian
Posizione della cartella contentlascia content/ di default
Base URL del sito<username>.github.io/<repo> (senza https://)
Risoluzione dei linkshortest funziona bene con Obsidian

Step 4 — Installa i plugin Quartz

npx quartz plugin install --from-config

Questo scarica e compila tutti i plugin dichiarati in quartz.config.yaml.

Se alcuni plugin falliscono la build, prova: npx quartz plugin install --latest

Step 5 — Collega le note Obsidian

Copia le tue note Obsidian nella cartella content/ del repository:

cp -r /percorso/al/vault/obsidian/* content/

Oppure puoi impostare content/ come cartella del vault direttamente in Obsidian:

  • Apri Obsidian → Apri vault da cartella → seleziona <tuo-repo>/content/

In questo modo lavori direttamente nella cartella che Quartz pubblicherà.

Nota: Se hai note nella cartella private/ del vault che non vuoi pubblicare, escludile aggiungendo in quartz.config.yaml:

filters:
  - ![[private/**]]

Step 6 — Anteprima locale

Avvia il server di sviluppo locale:

npx quartz build --serve

Apri il browser su http://localhost:8080 — vedrai il tuo garden con graph view, search e backlink già funzionanti. Il server si ricarica automaticamente ad ogni modifica.

Step 7 — Configura GitHub Pages

7a. Crea il workflow di deploy

Nella cartella del progetto crea il file .github/workflows/deploy.yml:

name: Deploy Quartz site to GitHub Pages
 
on:
  push:
    branches:
      - v5
 
permissions:
  contents: read
  pages: write
  id-token: write
 
concurrency:
  group: "pages"
  cancel-in-progress: false
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # necessario per i timestamp git
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - name: Cache dependencies
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-
      - name: Cache Quartz plugins
        uses: actions/cache@v5
        with:
          path: .quartz/plugins
          key: ${{ runner.os }}-plugins-${{ hashFiles('quartz.lock.json') }}
          restore-keys: |
            ${{ runner.os }}-plugins-
      - name: Install Dependencies
        run: npm ci
      - name: Install Quartz plugins
        run: npx quartz plugin install
      - name: Build Quartz
        run: npx quartz build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public
 
  deploy:
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

7b. Abilita GitHub Pages nelle impostazioni del repository

  1. Vai su Settings → Pages nel tuo repository GitHub
  2. In Source seleziona GitHub Actions
  3. Salva

7c. Rimuovi eventuali environment esistenti (se necessario)

Se ricevi errori di permesso sul deploy, vai su Settings → Environments, elimina l’environment github-pages esistente (icona cestino). GitHub Actions lo ricreerà correttamente al prossimo push.

Step 8 — Pubblica e sincronizza

Per il primo push usa:

npx quartz sync --no-pull

Per tutti gli aggiornamenti successivi:

npx quartz sync

Questo comando fa commit delle modifiche, le pusha su GitHub e avvia automaticamente la GitHub Action che ricostruisce e pubblica il sito. In circa 1-2 minuti il garden sarà live su:

https://<tuo-username>.github.io/<tuo-repo>

Conclusioni

Il flusso di lavoro quotidiano diventa semplicissimo:

  1. Scrivi o modifica note in Obsidian (nella cartella content/)
  2. Esegui npx quartz sync
  3. In 1-2 minuti le modifiche sono live online

Quartz supporta nativamente backlink, graph view, full-text search, LaTeX, syntax highlighting e preview al passaggio del mouse — tutto senza configurazione aggiuntiva.

Prossimi passi consigliati

  • Configura un dominio personalizzato tramite le impostazioni DNS e GitHub Pages
  • Personalizza il tema e il layout editando quartz.config.yaml
  • Usa i tag nelle note per creare pagine di indice automatiche
  • Aggiungi il plugin RSS per permettere agli utenti di seguire il garden

Vedi anche

Obsidian Vault Digital Garden GitHub Pages

Vista grafico