Questo repository contiene il codice sorgente del mio sito web personale e blog, disponibile online all'indirizzo: 👉 lucabontempi.com
Il sito è un generatore di siti statici basato su Hugo con deploy continuo e gestione dei contenuti tramite interfaccia grafica.
La struttura dei template, gli override rispetto a PaperMod e le verifiche del cambio lingua sono descritti in docs/theme-maintenance.md.
- Generatore di siti statici: Hugo (versione pinnata in
netlify.toml,HUGO_VERSION) - CMS per i contenuti: Decap CMS (accessibile da
/admin/) - Hosting e Deploy: Netlify (configurato tramite
netlify.toml) - Analytics: GoatCounter — gratuito, senza cookie, non richiede privacy policy/cookie banner
- Lingua del sito: inglese (
defaultContentLanguageinconfig.yml); il contenuto è misto e le pagine italiane lo dichiarano una per una — vedi Lingua delle pagine
Se vuoi eseguire il sito in locale sul tuo computer per testare delle modifiche o vedere un'anteprima degli articoli, segui questi passaggi:
- Git
- Hugo — versione Extended, stessa versione indicata in
netlify.toml(HUGO_VERSION), per evitare differenze di comportamento tra build locale e build di produzione - Node.js (LTS) — serve solo per scaricare gli asset di KaTeX (il rendering delle formule matematiche, usato in alcuni articoli), che vengono auto-ospitati invece di dipendere da un CDN esterno
-
Clona questo repository ed entra nella cartella del progetto:
git clone https://github.com/lucabnt/lb-website.git cd lb-website -
Inizializza il tema (submodule git):
git submodule update --init --recursive
-
Installa le dipendenze npm (genera gli asset di KaTeX in
static/vendor/katex/):npm install
-
Avvia il server di sviluppo di Hugo:
hugo server
-
Apri http://localhost:1313 nel browser. Il sito si ricarica automaticamente ad ogni modifica dei contenuti o dei template.
Nota: alcune funzionalità (analytics, Open Graph, dati strutturati) sono attive solo in build "production" — per vederle in locale usa
hugo server --environment production.
Ad ogni push su main, il workflow .github/workflows/build-check.yml esegue la stessa build di produzione usata da Netlify e verifica che:
- la build non produca errori;
- ogni pagina pubblicata sia effettivamente generata — nasce da un bug intermittente per cui la build poteva saltare un post senza fallire, lasciando un 404 silenzioso in produzione. La causa è stata trovata e corretta (vedi Tema PaperMod), ma il controllo resta come rete di sicurezza: una pagina che sparisce senza far fallire la build è un guasto che Netlify non segnala;
- non ci siano link interni rotti (controllo bloccante);
- non ci siano link esterni rotti (controllo informativo, non blocca la CI: il link rot su siti di terzi non dipende da questo repository).
Oltre a tags (l'argomento) e categories, il sito ha una tassonomia series per i post che compongono una sequenza da leggere in ordine. Ogni puntata dichiara:
series: ["Ciclismo giovanile e professionismo"]
series_weight: 1 # posizione nella serie
tags: ["ciclismo-giovanile"]
lang: it # la serie è in italiano, il sito è in inglese
locale: it_ITseries_weight — e non la data — determina l'ordine: una puntata pubblicata in ritardo o retrodatata resta comunque al posto giusto.
Ogni serie ha una pagina propria in content/series/<slug>/_index.md, che serve a due cose: dare alla serie un titolo scritto a mano (altrimenti Hugo lo genera mettendo in maiuscolo ogni parola, congiunzioni comprese) e un'introduzione. Se la serie esce a puntate, episodes_total fissa il totale finale, altrimenti il primo post annuncerebbe «puntata 1 di 1»:
title: "Ciclismo giovanile e professionismo"
episodes_total: 9
⚠️ Il nome della cartella deve combaciare esattamente con lo slug del nome della serie così come Hugo lo genera dal valore scritto inseries:nei post. Se non combacia il guasto è silenzioso: Hugo costruisce due pagine separate, una con il titolo e l'introduzione ma senza post, e una con i post ma senza titolo e introduzione, e nessuna delle due segnala l'errore.Quando lo slug conterrebbe accenti o dieresi, la cartella deve tenerli lo stesso (
content/series/one-year-in-tübingen/), altrimenti l'accoppiamento salta. Per pubblicare comunque un indirizzo pulito si usaurl:—slug:sui termini di tassonomia viene ignorato:title: "One year in Tübingen" url: /series/tuebingen/
Dentro i post non va scritto nulla: layouts/_partials/series_nav.html aggiunge da sé la riga «Part N of M» sopra il testo e l'elenco delle puntate in fondo, con quella corrente evidenziata. Aggiungere o riordinare una puntata aggiorna tutte le altre.
Hugo usa ora il multilingua nativo en e it. I nomi dei file determinano
la lingua: articolo.md o articolo.en.md per inglese, articolo.it.md
per italiano. lang e locale descrivono anche HTML e anteprime social.
Le pagine italiane esistenti mantengono il loro URL con url: /blog/.../.
Per aggiungere una traduzione con un nome diverso, dare alle due versioni
lo stesso translationKey, ad esempio translationKey: app-store-review.
Hugo collega le pagine e PaperMod mostra il selettore verso la versione reale,
sia nell'header sia nei metadati. I contenuti monolingua non hanno selettore.
La homepage non mostra il selettore e Home rimanda sempre alla radice. Un pulsante a bussola apre Explore / Esplora.
About e ora separato in due versioni, riusando i testi esistenti.
Le traduzioni AI vengono scritte e revisionate come normali pagine Markdown:
nessuna traduzione automatica lato lettore. Non creare versioni vuote o copie
nella lingua sbagliata. I nuovi file italiani hanno normalmente URL /it/.../;
url con slash iniziale permette di mantenere un indirizzo preesistente.
Per i riferimenti ad altre lingue usare, ad esempio,
{{< ref path="cv" lang="en" >}}.
Poche cose, ma vanno fatte a mano. Nessuna è urgente: sono tutte "quando capita".
Il bundle è caricato da unpkg bloccato a una versione esatta e verificato con Subresource Integrity: se il file servito dal CDN cambiasse, il browser si rifiuterebbe di eseguirlo. È la protezione più importante del sito, perché /admin/ è l'unico punto in cui gira codice di terze parti insieme a una sessione autenticata con accesso in scrittura al repository.
Il rovescio della medaglia è che gli aggiornamenti non sono automatici (Dependabot non sa aggiornare un hash dentro un file HTML). Per aggiornare:
npm view decap-cms version # ultima versione disponibile
node scripts/decap-sri.js <versione> # stampa src e integrity aggiornatiIncolla i due valori in static/admin/index.html, fai il deploy e apri /admin/ una volta per confermare che il CMS carichi. Se l'hash fosse sbagliato la pagina resterebbe vuota: il guasto è evidente, non silenzioso.
Cadenza consigliata: una o due volte l'anno, o quando serve una funzionalità nuova.
HUGO_VERSION determina sia la build di produzione sia quella della CI. Quando la aggiorni, allinea anche il binario locale alla stessa versione: un disallineamento fra locale e produzione è già stato causa di comportamenti divergenti difficili da diagnosticare.
È pinnato a un commit specifico, quindi non si aggiorna da solo. Per aggiornarlo:
cd themes/hugo-PaperMod && git fetch && git checkout <tag-o-commit> && cd ../..
git add themes/hugo-PaperMod && git commit -m "Aggiorna PaperMod"L’inventario degli override, le differenze rispetto al tema e i controlli da eseguire dopo un aggiornamento sono nella guida di manutenzione. I file del submodule non vengono modificati.
Il perché di
schema_json.html: il template del tema costruiva il JSON-LD del breadcrumb mettendo la virgola prima dell'ultimo elemento in base alla profondità del percorso, non al numero di elementi effettivamente scritti. Quandosite.GetPagenon risolveva la sezione padre usciva"itemListElement": [, {...}], JSON non valido: il minificatore rifiutava la pagina e la build falliva. Colpiva solo i post del blog, perché sono le uniche pagine dentro una sezione.
Gestite da Dependabot (.github/dependabot.yml), che apre una pull request mensile. Le action sono pinnate al commit SHA — un tag come v7 può essere spostato, un SHA no — e Dependabot aggiorna SHA e commento della versione insieme.
Che in Netlify Identity la registrazione sia impostata su Invite only e non Open: con Open chiunque potrebbe registrarsi e, a seconda della configurazione di git-gateway, ottenere accesso al CMS.
La homepage resta in Profile Mode e non mostra RSS o selezione della lingua.
Il blog e le serie espongono il proprio RSS, collegato anche dal riquadro
in fondo alle puntate. Il pulsante apre XML; l'iscrizione si effettua nel
proprio lettore RSS. Il feed del blog unisce gli originali nelle due lingue, senza duplicarli con le traduzioni;
i feed delle serie seguono la lingua della serie. Le bozze sono escluse.
layouts/rss.xml personalizza il feed per evitare che il multilingua escluda
le pubblicazioni italiane dal feed comune.
La ricerca nativa PaperMod in /search/ legge layouts/index.json, che
include i contenuti pubblicati di tutti i siti lingua, senza le bozze.
layouts/blog/list.html deriva da PaperMod e aggrega entrambe le lingue.
Mostra tutti i post senza paginazione per filtrare l'intero archivio.
I pulsanti English e Italiano partono entrambi inattivi: si vedono solo le
versioni originali, una scheda per articolo. Un clic mostra le versioni nella
lingua scelta; un secondo clic sul pulsante attivo ripristina gli originali.
Anche senza JavaScript le traduzioni sono nascoste e restano gli originali.
Decap crea nuovi post con suffisso .en.md o .it.md secondo il campo lingua.
La chiave traduzione collega articoli che hanno titoli o nomi di file diversi.
Gli override layouts/blog/list.html e layouts/_partials/header.html vanno
confrontati con il tema dopo un aggiornamento di PaperMod. L'header cambia
solo Home (sempre radice) e il selettore (solo traduzioni della pagina).
Ogni post ha una versione nell'altra lingua, comprese le bozze, che restano bozze. Le traduzioni hanno aiTranslated: true e originalLanguage nel front matter. La nota in layouts/_partials/translation_notice.html appare solo sulle versioni tradotte e rimanda all'originale. Il campo e disponibile in Decap.
La versione italiana di determinants_of_download_on_mobile_app_stores traduce soltanto la Premessa: titolo e testo da Abstract in poi sono conservati, con marcatura della lingua per gli screen reader. Gli altri post sono tradotti integralmente, incluse note e didascalie. I testi dentro le immagini restano quelli dei grafici originali. Le traduzioni usano gli stessi asset, con percorsi assoluti per evitare immagini rotte negli URL tradotti.
Explore (/explore/) ed Esplora (/it/explore/) usano layouts/explore.html e data/explore.yaml. Mostrano solo tre percorsi, senza selezione iniziale. Gli elenchi provengono dalle serie della lingua corrente, ordinati con series_weight; le bozze non appaiono in produzione. Le pagine delle serie sono collegate come traduzioni native. La struttura condivisa evita duplicazioni del layout.
Dopo un aggiornamento del tema confrontare anche index_profile.html: l'override aggiunge etichette accessibili e un'icona SVG locale opzionale ai pulsanti della homepage.