L'architettura¶
Lo stack tecnico¶
Il sistema si compone di quattro elementi:
MkDocs è un generatore di siti statici progettato specificamente per documentazione. Prende file Markdown e li trasforma in un sito web navigabile, con ricerca integrata, navigazione automatica, e design responsive.
Material for MkDocs è un tema per MkDocs che aggiunge funzionalità avanzate: modalità chiaro/scuro, navigazione a tab, table of contents, callout per note e avvisi, e molte altre. È usato da Google, Microsoft, Amazon, e migliaia di progetti open source. Da novembre 2025 tutte le funzionalità sono gratuite.
GitHub ospita i file sorgente (Markdown) in un repository, gestisce il versioning, e tramite GitHub Actions automatizza il processo di build. GitHub Pages serve il sito web generato.
Un dominio (proprio o sottodominio) punta al sito su GitHub Pages. La configurazione DNS è l'unico passaggio che richiede accesso al pannello di gestione del dominio.
Perché queste scelte¶
La decisione è emersa da un'analisi comparativa di diverse opzioni. Le alternative considerate includevano:
Docusaurus (Facebook/Meta): potente ma richiede familiarità con React e Node.js. Eccessivo per chi non è sviluppatore.
GitBook: ottima esperienza utente ma modello freemium con costi significativi (65$/mese per funzionalità professionali) e vendor lock-in.
Sphinx: standard per documentazione Python, ma usa reStructuredText invece di Markdown, con curva di apprendimento più ripida.
WordPress con plugin documentazione: possibile, ma aggiunge complessità (database, aggiornamenti di sicurezza, plugin da mantenere) senza vantaggi reali per contenuti statici.
MkDocs con Material è emerso come il miglior compromesso: semplicità di Markdown, funzionalità professionali, nessun costo, nessun lock-in, comunità attiva.
Per l'hosting, GitHub Pages ha vinto su Netlify e Cloudflare Pages per un motivo pragmatico: se già si usa GitHub per il versioning, aggiungere Pages non introduce nuovi servizi da gestire. Il piano gratuito è sufficiente per documentazione con traffico normale. GitHub Pro (4$/mese) aggiunge la possibilità di repository privati con Pages pubbliche, utile per sviluppare in privato e pubblicare quando pronti.
L'architettura dei contenuti¶
Il sito è organizzato come monorepo: un unico repository GitHub contiene tutti i manuali. Ogni manuale è una cartella separata dentro docs/.
docs-ai-know/
├── docs/
│ ├── index.md # Home page del sito
│ ├── mkdocs-ghpages/ # Questo manuale
│ │ ├── index.md
│ │ ├── introduzione.md
│ │ └── ...
│ ├── altro-manuale/ # Futuro manuale
│ │ └── ...
│ └── assets/ # Risorse condivise
├── mkdocs.yml # Configurazione
└── .github/workflows/deploy.yml # Automazione
Questa scelta ha implicazioni:
Pro: un solo repository da gestire, un solo workflow di deploy, navigazione coerente tra manuali, URL puliti (dominio.it/manuale/).
Contro: i manuali non sono completamente indipendenti. Un collaboratore che lavora su un manuale ha potenzialmente accesso a tutti. Ogni modifica, anche a un solo manuale, triggera il rebuild dell'intero sito.
Per progetti con requisiti di separazione più stringenti (team diversi su manuali diversi, necessità di deploy indipendenti), esistono architetture alternative che richiedono però servizi aggiuntivi come Netlify per il routing tra repository separati.
La struttura di navigazione¶
Ogni manuale segue una struttura a tre livelli:
Livello 1 (Tab): le sezioni principali, visibili nella barra di navigazione orizzontale. Per manuali compatti può esserci un solo tab.
Livello 2 (Capitoli): le voci nella sidebar laterale. Corrispondono ai file Markdown principali.
Livello 3 (Sezioni): i titoli interni alle pagine, navigabili tramite la table of contents sulla destra.
Questa struttura emerge dalla configurazione in mkdocs.yml e dalla gerarchia dei file Markdown. Non richiede codice, solo organizzazione dei contenuti.