Onda

Un tema per Ghost 6 caldo e ondulato, pensato per blog personali, magazine e newsletter.

Onda mette al centro la lettura: card ampie, titoli grandi, molto respiro bianco e qualche onda dove serve, nei titoli di sezione, nei divisori e sul bordo delle immagini. I colori del gradiente si cambiano da Ghost Admin in due clic e il tema ha la modalità scura. Funziona in italiano e in inglese senza toccare il codice.

Non c'è niente da compilare. Niente Node, niente Gulp, niente bundle: si carica lo zip e si parte.

Indice

• Cosa trovi nel tema
• Requisiti
• Installazione
• Primi passi dopo l'attivazione
• Impostazioni del tema
• Social network
• Personalizzazione
• Sviluppo
• Struttura dei file
• Privacy e GDPR
• Licenza

Cosa trovi nel tema

Chiaro	Scuro	Mobile

Home

• Slider degli articoli in evidenza con indice numerato accanto: autoplay con barra di avanzamento, frecce, pallini, swipe e tastiera. Si ferma quando ci passi sopra col mouse. Senza JavaScript resta visibile la prima slide.
• Pulsante «Carica altri articoli» che aggiunge i post senza ricaricare la pagina. Se il JavaScript non c'è, torna la paginazione classica.

Lettura

• Barra di avanzamento della lettura, pulsanti di condivisione (X, Bluesky, Facebook, LinkedIn, WhatsApp, copia link), box dell'autore con i suoi social, commenti nativi di Ghost e articoli correlati per tag.
• Supporto completo alle card dell'editor di Ghost, comprese le immagini wide e full width.
• Template alternativo Cover per gli articoli: immagine a tutta pagina con il titolo sopra. Si sceglie dal pannello delle impostazioni del post, alla voce Template.

Sidebar

• Widget Chi sono con i social del sito, Categorie con il numero di articoli, Articoli in evidenza (solo se ce ne sono) e Newsletter.
• Gli ultimi due widget restano agganciati allo scorrimento, mentre quelli sopra scorrono normalmente: così nessun widget finisce fuori dallo schermo.

Membri e newsletter

• Iscrizione tramite Portal, form nel footer, fascia di invito alla newsletter tra contenuto e footer.
• Badge «Membri» sulle card degli articoli riservati.

Tutto il resto

• Modalità chiara, scura o automatica (segue il sistema), con pulsante nell'header. La scelta del lettore viene ricordata e la pagina non lampeggia di bianco al caricamento.
• Ricerca nativa di Ghost, menu mobile accessibile da tastiera, animazioni allo scroll che si spengono da sole con prefers-reduced-motion.
• Font ospitati nel tema, senza Google Fonts né altre richieste a terze parti (vedi Privacy e GDPR).
• Font e colore accent del brand di Ghost (--gh-font-heading, --gh-font-body, --ghost-accent-color).
• Traduzioni in italiano e in inglese.

Requisiti

• Ghost 6.0 o successivo, self-hosted oppure Ghost(Pro).
• Un browser recente per chi legge: il tema usa :has() e color-mix(), supportati da Chrome, Edge, Firefox e Safari usciti dal 2023 in poi.

Installazione

Scegli il metodo che fa per te. Il primo va bene quasi sempre.

1. Caricare lo zip da Ghost Admin (consigliato)

È l'unico metodo possibile su Ghost(Pro) e il più rapido ovunque.

1. Procurati il file onda.zip:
   • scaricalo dalla pagina Releases del repository, se presente;
   • oppure crealo da questa cartella (vedi Creare il pacchetto zip);
   • oppure, su GitHub, usa Code → Download ZIP. In questo caso Ghost accetta lo zip così com'è, anche se dentro ci sono la cartella docs/ e gli altri file del repository.
2. Accedi a Ghost Admin (https://iltuosito.it/ghost).
3. Apri Settings → Design & branding e clicca Change theme.
4. Clicca Upload theme e seleziona onda.zip.
5. A caricamento finito, clicca Activate.

Per aggiornare il tema a una versione nuova si ripete la stessa procedura: Ghost riconosce che il tema esiste già e chiede se sovrascriverlo. Le impostazioni fatte in Customize restano.

Se Ghost rifiuta il file, quasi sempre il problema è lo zip: deve contenere package.json e index.hbs nella radice oppure dentro una sola cartella. Uno zip che contiene un altro zip non funziona.

2. Clonare il repository sul server (Ghost self-hosted)

Utile se vuoi aggiornare il tema con un semplice git pull.

cd /var/www/ghost/content/themes
git clone https://code.federicorinaldi.dev/federico/onda-ghost-theme.git onda

cd /var/www/ghost
ghost restart

Poi attiva Onda da Settings → Design & branding → Change theme. Adatta il percorso /var/www/ghost a quello della tua installazione.

Per gli aggiornamenti successivi:

cd /var/www/ghost/content/themes/onda && git pull

cd /var/www/ghost && ghost restart

Il riavvio serve perché Ghost legge package.json e le impostazioni del tema solo all'avvio.

3. Ambiente locale per lo sviluppo

Serve Ghost-CLI e una versione di Node supportata da Ghost 6.

npm install -g ghost-cli

mkdir ghost-locale && cd ghost-locale && ghost install local

Collega il tema alla cartella dei temi con un link simbolico, così ogni modifica è subito visibile:

ln -s /percorso/del/repository/onda content/themes/onda

ghost restart

Apri http://localhost:2368/ghost, crea l'utente di prova e attiva Onda. In modalità sviluppo le modifiche a template, CSS e JavaScript si vedono ricaricando la pagina. Un file nuovo (per esempio un partial), le modifiche a package.json e quelle ai file di locales/ richiedono invece ghost restart.

Primi passi dopo l'attivazione

Bastano dieci minuti per avere il tema a posto.

1. Lingua. In Settings → General → Publication language scrivi it per l'italiano oppure en per l'inglese. Il tema traduce pulsanti, etichette e date di conseguenza.
2. Menu. In Settings → Navigation il menu Primary va nell'header e il menu Secondary nel footer.
3. Articoli in evidenza. Segna come Feature this post tre o quattro articoli: compaiono nello slider della home e nel widget della sidebar. Se preferisci lo slider con gli ultimi articoli, cambia Slider source nelle impostazioni del tema.
4. Social. Inserisci gli account del sito in Settings → General → Social accounts e quelli degli autori nel loro profilo, da Settings → Staff.
5. Brand. Logo, icona, colore accent e font si impostano in Settings → Design & branding → Customize, scheda Brand. I colori del gradiente sono nelle impostazioni del tema, descritte qui sotto.
6. Newsletter. Se vuoi raccogliere iscritti, attiva i membri in Settings → Membership. Form e fasce di iscrizione compaiono solo quando i membri sono attivi.

Impostazioni del tema

Si trovano in Settings → Design & branding → Customize, divise nelle schede Site wide, Homepage e Post.

Impostazione	Scheda	A cosa serve
Navigation layout	Site wide	Logo a sinistra oppure al centro dell'header
Color scheme	Site wide	Schema iniziale: chiaro, scuro o automatico
Show theme toggle	Site wide	Mostra il pulsante chiaro/scuro nell'header
Title font	Site wide	Font dei titoli (sans moderno, serif elegante, arrotondato), usato quando nel brand non è scelto un font
Gradient start, Gradient end	Site wide	I due colori del gradiente di pulsanti, numeri e decorazioni
Soft background	Site wide	Colore di fondo di box, widget e sezioni evidenziate
Footer description	Site wide	Testo del footer; se vuoto usa la descrizione del sito
Show sidebar	Site wide	Sidebar in home, nelle pagine dei tag e degli autori
About text, About image	Site wide	Testo e immagine del widget Chi sono
Show newsletter box, Newsletter title	Site wide	Fascia di invito alla newsletter e il suo titolo
Show featured slider, Slider source	Homepage	Slider in home e da dove prende gli articoli
Post layout	Post	Articolo con sidebar oppure a tutta larghezza
Show reading progress	Post	Barra di avanzamento della lettura
Show share buttons	Post	Pulsanti di condivisione
Show author box	Post	Box dell'autore a fine articolo
Show related posts	Post	Articoli correlati per tag

Il tema usa tutte e 20 le impostazioni personalizzate che Ghost consente.

Social network

Il tema mostra un'icona per ogni account compilato in Ghost, sia per il sito (footer e widget Chi sono) sia per ogni autore (pagina autore e box a fine articolo). Le reti supportate sono quelle previste da Ghost:

X · Facebook · LinkedIn · Bluesky · Threads · Mastodon · TikTok · YouTube · Instagram

I link hanno rel="me", quindi Mastodon può mostrare il sito come link verificato nel tuo profilo.

PeerTube, Pixelfed e altri servizi non hanno un campo in Ghost. Il modo più semplice per collegarli è aggiungerli come voci del menu Secondary.

Personalizzazione

Colori. Per la maggior parte dei casi bastano le impostazioni Gradient start, Gradient end e Soft background. Per interventi più profondi, tutti i colori sono variabili CSS all'inizio di assets/css/screen.css, nella sezione Tokens, con le varianti scure nella sezione Dark mode.

Codice nell'header. Piccole modifiche di stile si possono fare senza toccare il tema, da Settings → Advanced → Code injection:

<style>
    :root { --radius: 8px; }
</style>

Traduzioni. Le stringhe sono in locales/en.json e locales/it.json. Per aggiungere una lingua copia en.json, rinominalo con il codice della lingua (ad esempio es.json), traduci i valori lasciando invariate le chiavi e imposta lo stesso codice in Publication language.

Template personalizzati. Ghost riconosce i file custom-*.hbs come template selezionabili dall'editor. custom-cover.hbs è un esempio da cui partire.

Sviluppo

Validare il tema

Prima di ogni rilascio conviene passare il tema a gscan, il validatore ufficiale di Ghost:

npm test

Il comando esegue gscan --v6 sulla cartella. In alternativa si può caricare lo zip su gscan.ghost.org.

Creare il pacchetto zip

Dalla cartella del repository, con almeno un commit:

npm run zip

Il pacchetto finisce in dist/onda.zip. Lo script usa git archive, che esclude da solo docs/ e i file di configurazione di git (le regole sono in .gitattributes).

Senza git, dalla cartella che contiene onda/:

zip -r onda.zip onda -x "*.DS_Store" "onda/.git/*" "onda/docs/*" "onda/dist/*" "onda/node_modules/*"

Pubblicare una versione nuova

1. Aggiorna version in package.json e il badge in cima a questo file.
2. Annota le modifiche in CHANGELOG.md.
3. Esegui npm test e npm run zip.
4. Crea il tag (git tag v1.3.0) e allega dist/onda.zip alla release su GitHub.

Struttura dei file

onda/
├── default.hbs            layout comune: head, header, footer
├── index.hbs              home e pagine dell'archivio
├── post.hbs               articolo
├── custom-cover.hbs       template articolo «Cover»
├── page.hbs               pagine statiche
├── tag.hbs, author.hbs    archivi per tag e per autore
├── error.hbs, error-404.hbs
├── partials/              header, footer, slider, card, sidebar, social, icone SVG…
├── assets/
│   ├── css/screen.css     tutto lo stile, organizzato in sezioni numerate
│   ├── js/main.js         JavaScript senza dipendenze
│   ├── fonts/             font WOFF2 e relative licenze OFL
│   └── images/
├── locales/               en.json, it.json
├── docs/screenshots/      immagini di questo README (escluse dallo zip)
└── package.json           metadati, impostazioni del tema, dimensioni delle immagini

Privacy e GDPR

Il tema non fa partire nessuna richiesta verso server di terze parti. Tutto quello che serve per mostrare la pagina sta dentro il tema e viene servito dal tuo dominio.

Cosa fa il tema

• Font ospitati in locale. Plus Jakarta Sans, Fraunces e Nunito sono in assets/fonts/ in formato WOFF2, con i soli set di caratteri latino e latino esteso. Niente Google Fonts, quindi l'indirizzo IP dei lettori non arriva a Google. Il browser scarica solo i font davvero usati: Fraunces e Nunito si caricano solo se li scegli in Title font.
• Nessun cookie, nessun tracciamento, nessun analytics. Il pulsante chiaro/scuro salva la scelta nel localStorage del browser (chiave onda-scheme). È una preferenza impostata dal lettore stesso e non viene mai inviata al server.
• Pulsanti di condivisione come semplici link. Non caricano script né pixel di X, Facebook, LinkedIn, Bluesky o WhatsApp. Il lettore contatta il social solo se clicca.
• Icone e illustrazioni sono SVG dentro il tema.

Cosa dipende da Ghost

Alcune risorse le aggiunge Ghost, non il tema, e si regolano dalla configurazione di Ghost.

1. Font del brand. Se in Settings → Design & branding → Customize → Brand scegli un font per titoli o testo, Ghost lo carica da fonts.bunny.net. Bunny Fonts dichiara di non registrare gli indirizzi IP, ma resta un servizio esterno. Per restare al 100% in locale, lascia entrambi i font su Theme default.

2. Portal, ricerca, commenti, form di iscrizione e barra degli annunci. Ghost li carica di default da cdn.jsdelivr.net. Su un'installazione self-hosted puoi servirli dal tuo dominio: scarica i file (trovi gli indirizzi e le versioni in uso nel sorgente HTML del sito), mettili in una cartella pubblica del tuo dominio (nell'esempio content/files/ghost-ui/ dentro l'installazione di Ghost) e indica i nuovi indirizzi in config.production.json:

   "portal": {
       "url": "https://iltuosito.it/content/files/ghost-ui/portal.min.js"
   },
   "sodoSearch": {
       "url": "https://iltuosito.it/content/files/ghost-ui/sodo-search.min.js",
       "styles": "https://iltuosito.it/content/files/ghost-ui/sodo-search.css"
   },
   "comments": {
       "url": "https://iltuosito.it/content/files/ghost-ui/comments-ui.min.js"
   },
   "signupForm": {
       "url": "https://iltuosito.it/content/files/ghost-ui/signup-form.min.js"
   },
   "announcementBar": {
       "url": "https://iltuosito.it/content/files/ghost-ui/announcement-bar.min.js"
   }
   

   Poi esegui ghost restart. A ogni aggiornamento di Ghost controlla che le versioni dei file siano ancora quelle giuste.

3. Gravatar e altri servizi di Ghost. Con questa voce in config.production.json Ghost smette di usare Gravatar per le immagini profilo, di controllare gli aggiornamenti e di inviare i ping ai servizi di indicizzazione:

   "privacy": {
       "useTinfoil": true,
       "useStructuredData": true
   }
   

   useTinfoil spegne tutte queste funzioni insieme. useStructuredData: true riaccende i dati strutturati per i motori di ricerca, che non contattano nessun servizio esterno.

4. Contenuti incorporati negli articoli. Video di YouTube o Vimeo, post social e altri embed inseriti nell'editor caricano risorse dai rispettivi servizi. Il tema non li modifica: valuta se servono e, se li usi, citali nella privacy policy.

Su Ghost(Pro) la configurazione del server non si può modificare. Il tema resta comunque privo di richieste esterne, mentre i punti 2 e 3 dipendono dall'hosting.

Il tema non sostituisce la privacy policy del sito. Se raccogli iscritti, l'informativa deve spiegare quali dati salva Ghost (email, nome, attività sulle newsletter) e, per gli abbonamenti a pagamento, il ruolo di Stripe. Per i casi specifici conviene sentire un consulente.

Licenza

Distribuito con licenza MIT: puoi usarlo, modificarlo e ridistribuirlo, anche per lavori commerciali, mantenendo l'avviso di copyright.

I font in assets/fonts/ (Plus Jakarta Sans, Fraunces, Nunito) sono rilasciati dai rispettivi autori con licenza SIL Open Font License 1.1: il testo di ogni licenza è nei file OFL-*.txt accanto ai font. Icone, illustrazioni e codice del tema sono originali.