NON toccare mai 2-PUBBLICA.bat e NON toccare mai 3-PULL.bat — sono di Mirco
SHELL: usare PowerShell con ; come separatore. Git è in PATH su PowerShell.
REGOLA: RAGIONAMENTO PRIMA DI MODIFICARE CSS
Prima di toccare qualsiasi CSS, Claude DEVE ragionare così:
Dove vive il colore che voglio cambiare? (body? tema skin? componente specifico?)
Minimal Mistakes ha layer multipli: skin (_sass/minimal-mistakes/skins/) → componente (.masthead, .greedy-nav, .sidebar) → global (body)
Sovrascrivere solo body { background } NON basta — ogni componente MM ha il suo background proprio
La navbar = .masthead + .masthead__inner-wrap + .greedy-nav — tutti e tre vanno sovrascritti
Usare SEMPRE !important per override su classi MM (il tema ha specificità alta)
Verificare sempre la skin attuale in _config.yml → minimal_mistakes_skin
Usare SEMPRE edit_block con old_string/new_string invece di riscrivere file interi
Prima di scrivere codice nuovo: cercare se esiste già una funzione/soluzione riutilizzabile
Esempio: editor pagine riusa stessa logica editor articoli (setPagCorpo/getPagCorpo speculari a setCorpo/getCorpo)
Se una funzione esiste già, richiamarla — non duplicarla
Riscrivere da zero SOLO se il codice esistente è incompatibile o la modifica supera il 70% del file
Ogni volta che si risolve un problema nuovo, Claude DEVE aggiornare questo file nella sezione “SOLUZIONI GIA’ RISOLTE” con: sintomo, causa, soluzione esatta. Questo vale sempre, senza che l’utente lo chieda. E’ parte del workflow standard.
PROGETTO
Stack: Jekyll + tema Minimal Mistakes (remote_theme) + GitHub Pages
NON esiste piu’ cms/ — e’ stata rimossa. Non ricrearla.
admin/index.html NON ha front matter Jekyll (niente — in cima).
Senza front matter Jekyll lo ignora -> GitHub Pages lo serve come statico puro.
Le modifiche all’admin si vedono subito, senza cache CDN.
Tab disponibili: Articoli, Pagine, Menu, Categorie, Token, Tema
Tab Tema: cambia minimal_mistakes_skin in _config.yml via API GitHub
ARCHITETTURA PAGINE
Home -> index.html (layout: home) -> _layouts/home.html
Blog -> _pages/blog.md (permalink: /blog/)
Categories -> _pages/category-archive.md
Tags -> _pages/tag-archive.md
About -> _pages/about.md
404 -> _pages/404.md Home e blog sono SEPARATI. Non confonderli.
MENU (_data/navigation.yml)
Voci attuali: Home /, Blog /blog/, Categories /categories/, Tags /tags/, About /about/ REGOLA: il menu si modifica SOLO in _data/navigation.yml. Mai nav custom nei layout.
LAYOUT HOME (_layouts/home.html)
Usa layout: default — eredita nav e footer da Minimal Mistakes automaticamente.
NON aggiungere nav o footer custom: verrebbero duplicati.
REGOLE OPERATIVE
Modifiche chirurgiche: tocca SOLO il file richiesto.
Layout custom: usano layout: default, mai nav/footer dentro.
File .bat: ASCII puro, zero accentate, zero cornici grafiche.
Articoli: nome YYYY-MM-DD-titolo.md, front matter con layout/title/date/categories/tags.
_config.yml: cambiare SOLO la riga necessaria. Skin attuale: default. Opzioni skin: default, dark, mint, sunrise, aqua, neon, plum, dirt, air.
PowerShell: separatore comandi e’ ; non &&.
COSA NON FARE
Non aggiungere front matter a admin/index.html (rompe la cache -> modifiche invisibili).
Non ricreare la cartella cms/ (rimossa, non serve).
Non creare nav/footer custom nei layout (doppio menu/footer).
Non installare Ruby/Jekyll localmente (build sul cloud GitHub).
Non suggerire Netlify/Vercel/CF Pages.
Non chiedere conferma per operazioni banali.
Non aggiungere url al navigation.yml che non esistono come pagine.
Questa sezione viene aggiornata automaticamente da Claude ogni volta che si risolve un problema.
PROBLEMA: CMS admin non mostra le modifiche online
SINTOMO: Modifichi admin/index.html, fai push, aspetti 2+ minuti, il sito mostra ancora la versione vecchia — anche in finestra incognito.
CAUSA: admin/index.html aveva front matter Jekyll (—layout: none— in cima). Jekyll processa il file e GitHub Pages CDN lo mette in cache aggressiva per ore.
SOLUZIONE IMMEDIATA:
Aprire admin/index.html
Rimuovere COMPLETAMENTE il blocco — front matter — (tutto tra i due —)
Il file deve iniziare con come prima riga assoluta
Push con 2-PUBBLICA.bat
Aspettare 60 secondi — le modifiche compaiono subito
VERIFICA: Cambia un testo visibile (es. titolo topbar), pusha, apri in incognito.
PROBLEMA: Editor visuale/markdown del CMS pubblica articolo vuoto
SINTOMO: Scrivi un articolo in modalita’ visuale (Quill), clicchi Pubblica, l’articolo viene creato su GitHub ma il corpo e’ vuoto.
CAUSA: La funzione pubblica() leggeva document.getElementById(‘corpo’).value invece di getCorpo(). In modalita’ visuale il testo e’ nel widget Quill, non nel textarea — quindi il textarea risultava vuoto.
SOLUZIONE: In pubblica(), sostituire: const corpo = document.getElementById(‘corpo’).value.trim(); con: const corpo = getCorpo().trim(); La funzione getCorpo() gestisce correttamente entrambe le modalita’.
PROBLEMA: Editor visuale CMS non funziona (Quill CDN)
SINTOMO: Tab “Visuale” non carica, toolbar assente, errori console su cdnjs.cloudflare.com
CAUSA: Quill.js caricato da CDN esterna — se la CDN è lenta o bloccata, l’editor non parte.
SOLUZIONE APPLICATA: Rimosso Quill completamente. Editor visuale riscritto con contenteditable + document.execCommand() nativo del browser. Zero dipendenze esterne. Funziona sempre, offline incluso.
FILE: admin/index.html — cercare id=”vis-editor” e class=”vis-toolbar”
NON reinstallare Quill o altre librerie esterne per l’editor visuale.
SINTOMO: Comando con && da errore “token non valido come separatore”.
CAUSA: PowerShell non accetta && come separatore di comandi (e’ bash/cmd).
SOLUZIONE: Usare ; come separatore. Esempio: cd “C:\percorso”; git add .; git commit -m “msg”; git push
ARCHITETTURA HOME PAGE (stile WordPress)
_includes/home-content.html = il contenuto reale della home (slider, sezioni) — modificabile dal CMS
Guide pratiche e appunti su tool, workflow e tecnologia web.
02
Esplora gli archivi
Naviga per categoria o tag per trovare esattamente quello che cerchi.
03
Rimani aggiornato
Segui il feed RSS per non perderti i nuovi articoli.
— NON toccare
index.html = stub minimale con layout: home — NON toccare
CMS → Pagine → 🏠 home → Modifica → modifica HTML della home → Salva
salvaPagina() gestisce home-content.html come HTML puro (niente front matter)
_pages/home.md esiste ma NON è usata come home — ha permalink /home-page/ (ignorabile)
DOVE: Sidebar → ⚙️ Impostazioni
COSA SI PUÒ MODIFICARE: titolo sito, email, descrizione, nome autore, bio, avatar, social (Twitter/Instagram/GitHub/Website)
PAGINA HOME: dropdown che lista tutte le pagine in _pages/ — scegli quale usare come home → salva il path in _config.yml come campo cms_homepage→ aggiorna automaticamente index.html con il layout della pagina scelta
FUNZIONE JS: caricaImpostazioni(), salvaImpostazioni(), aggiornaIndexHome()
IMPORTANTE: salvaImpostazioni() legge e riscrive _config.yml con regex chirurgiche, non sostituisce tutto il file
Con questo setup Claude legge i file reali del progetto prima di suggerire modifiche
PROBLEMA: blog.md ignorato — il blog mostra lista semplice invece del layout custom
SINTOMO: Modifichi _pages/blog.md (layout, bottoni, stile), fai push, ma il sito mostra sempre una lista semplice con punti elenco. Le modifiche non si vedono mai.
CAUSA: _config.yml aveva paginate: 5 e il plugin jekyll-paginate. Jekyll-paginate bypassa completamente _pages/blog.md e genera /blog/ con il suo layout di default.
SOLUZIONE:
In _config.yml commentare o rimuovere paginate: 5 e paginate_path: /page:num/
Rimuovere jekyll-paginate dalla lista plugins
Push con 2-PUBBLICA.bat
Dopo la build Jekyll usa correttamente _pages/blog.md
NOTA: Senza paginazione tutti gli articoli sono visibili in lista scorrevole. Gestibile fino a 50-100 post. Se servisse paginazione in futuro, va implementata in Liquid direttamente in blog.md.
PROBLEMA: /blog/ sempre intercettato da Jekyll — layout custom ignorato
SINTOMO: Modifichi _pages/blog.md (layout, bottoni, stile), fai push, ma /blog/ mostra sempre la lista semplice di Minimal Mistakes. Anche rimuovendo jekyll-paginate il problema persiste.
CAUSA: Minimal Mistakes intercetta il path /blog/ a livello di tema e lo gestisce internamente. Il front matter di blog.md viene ignorato per quel permalink specifico.
SOLUZIONE FUNZIONANTE: Cambiare il permalink da /blog/ a /articoli/ (o qualsiasi altro path non riservato da MM)
In _pages/blog.md: cambiare permalink: /blog/ → permalink: /articoli/
In _data/navigation.yml: cambiare url: /blog/ → url: /articoli/
Push con 2-PUBBLICA.bat
Il layout custom viene rispettato su /articoli/
COSA NON FUNZIONA:
Cambiare layout nel front matter di blog.md (sovrascrive i defaults ma MM intercetta lo stesso)
Aggiungere eccezioni nei defaults di _config.yml
Creare layout blog-custom.html personalizzato (MM bypassa comunque /blog/)
Rimuovere jekyll-paginate (non era quello il problema)
STATO ATTUALE: Blog accessibile su /articoli/ con layout bello, bottone “Leggi tutto →”, immagini, categorie, tag.