Come Creare Documentazione Pulita Senza Gigabyte di node_modules
Quando avvii un nuovo progetto o gestisci una libreria in un team, la questione della documentazione di base sorge inevitabilmente. Diciamo che non hai bisogno di un portale mostruoso con routing dinamico, componenti reattivi e centinaia di megabyte di dipendenze. Vuoi solo scrivere qualche file Markdown, premere un pulsante e ottenere un sito pulito con navigazione ad albero, ricerca e adattamento mobile.
Docusaurus o VuePress sono scelte comuni in queste situazioni. Sono validi, ma comportano un'intera marea di pacchetti npm. Se vuoi evitare Node.js nella tua pipeline di build e valorizzare una generazione ultraveloce, vale la pena dare un'occhiata al tema Hugo Book di Alexander Shpak.
Cos'è questo tema e per chi è
Hugo Book è un template minimalista per il generatore di siti statici Hugo, stilizzato come un normale libro con un menu laterale. L'autore del progetto, Alexander Shpak, aveva un obiettivo chiaro: creare un tema dal design pulito che funzioni velocemente e non costringa gli utenti a trascorrere ore a scavare nei file di configurazione.
Il repository ha accumulato oltre 4.000 stelle su GitHub, il che è piuttosto rispettabile per un tema Hugo specializzato. Il template rileva il Markdown standard e costruisce automaticamente una struttura ad albero delle pagine basata sulla nidificazione delle cartelle.
Caratteristiche principali sotto il cofano
A differenza di molti strumenti web moderni, Hugo Book segue una dieta rigorosa. La funzionalità principale del sito funziona interamente senza JavaScript. L'attivazione del menu mobile, l'espansione delle sezioni nidificate e la navigazione ad albero sono tutte realizzate in CSS puro.
Le funzionalità pratiche includono:
- Tema scuro integrato. Si adatta automaticamente alle impostazioni del sistema operativo, ma puoi anche aggiungere un interruttore manuale.
- Supporto multilingua out of the box. Hugo può gestire strutture di cartelle parallele per lingue diverse, e il tema renderizza correttamente un selettore di versione.
- Shortcode integrati convenienti. Per stilizzare note, avvisi, bei pulsanti e tab di codice, non devi inventare workaround personalizzati.
- Ricerca e commenti integrati. La ricerca può essere implementata tramite uno script leggero integrato (FlexSearch) o servizi di terze parti.
Il principio dell'intervento minimo
L'autore nota specificamente nella filosofia del progetto: il tema non dovrebbe interferire con i layout degli utenti o sovraccaricare la configurazione. Per lanciare un sito, letteralmente non hai bisogno di impostare alcun parametro specifico in config.toml o hugo.toml. Il template rileva la struttura standard dei contenuti di Hugo.
Se hai bisogno di stili personalizzati, puoi sovrascrivere il CSS in un paio di righe attraverso un file di estensione speciale, senza toccare il codice sorgente del tema. Questo ti salva dai mal di testa di manutenzione quando il tema si aggiornerà tra qualche mese.
Avvio rapido
Avrai bisogno della versione estesa di Hugo (Hugo extended) versione 0.158 o superiore installata. Il processo di configurazione richiede due minuti.
Il percorso più semplice è usare il repository starter già pronto:
git clone https://github.com/alex-shpak/hugo-book-starter my-docs
cd my-docs
git submodule update --init --remote
hugo server --minify
Dopo aver avviato il server locale su http://localhost:1313, si aprirà un sito di documentazione pronto all'uso. Quando modifichi i file Markdown, Hugo aggiorna la pagina nel browser quasi istantaneamente. Il tempo di build per siti con un paio di centinaia di pagine di solito non supera una frazione di secondo.
Shortcode per il layout del testo
Il Markdown standard può essere troppo limitato quando hai bisogno di evidenziare una nota importante o creare colonne. Hugo Book ha una serie di shortcode integrati.
Per esempio, lo shortcode hint viene usato per bei blocchi informativi:
{{< hint info >}}
Здесь можно написать полезную подсказку для читателя.
{{< /hint >}}
{{< hint warning >}}
А так оформляется предупреждение о возможных ошибках.
{{< /hint >}}
E se hai bisogno di mostrare esempi di codice per diversi sistemi operativi o linguaggi di programmazione, lo shortcode tabs è utile:
{{< tabs "unique-id" >}}
{{< tab "Linux" >}}
sudo apt install my-tool
{{< /tab >}}
{{< tab "macOS" >}}
brew install my-tool
{{< /tab >}}
{{< /tabs >}}
Approccio al versioning
Il tema è distribuito sotto licenza MIT. L'autore usa il versioning incrementale (es. v0.13.0, v0.14.0). Breaking changes tra le release capitano occasionalmente, quindi per la produzione è meglio fissare un tag specifico invece di restare sul branch main.
Dove torna utile
Il tema è perfetto per:
- Documentazione tecnica per librerie open source
- Knowledge base interna del team o Wiki aziendale
- Istruzioni di deployment e API
- Blog di ingegneria personale o raccolta di appunti
Se hai bisogno di forte interattività, grafica 3D direttamente nella documentazione, o integrazione profonda con componenti React, Hugo Book probabilmente non fa per te. In quel caso, dovresti guardare verso Docusaurus o Astro Starlight. Ma per le attività di documentazione tipiche, la semplicità di Hugo Book è più che sufficiente.
Insidie
Con tutti i vantaggi, devi capire le sfumature dell'infrastruttura di Hugo. Il motore di templating Go HTML Templates su cui si basa Hugo ha una sintassi specifica. Se vuoi riscrivere radicalmente la struttura dell'header o del footer, dovrai investire tempo nell'apprendimento della struttura dei template Go.
Inoltre, l'indice di ricerca per la ricerca locale viene generato al momento della build. Per siti enormi con decine di migliaia di pagine, il file di ricerca può diventare pesante, anche se per guide tipiche questo non è affatto un problema.
In sintesi
Hugo Book è uno strumento onesto senza fronzoli inutili. Fa esattamente ciò che promette: trasforma un mucchio di cartelle con Markdown in un sito veloce, pulito e leggibile. Nessun pacchetto npm da installare, nessuna build prolungata e nessuna configurazione complessa.
Progetti correlati