Hoe bouw je schone documentatie zonder gigabytes aan node_modules
Wanneer je een nieuw project start of een bibliotheek beheert in een team, komt de vraag naar basale documentatie onvermijdelijk naar voren. Stel dat je geen enorm portaal nodig hebt met dynamische routing, reactieve componenten en honderden megabytes aan afhankelijkheden. Je wilt gewoon een paar Markdown-bestanden schrijven, op een knop drukken en een schone site krijgen met boomnavigatie, zoekfunctie en mobiele aanpassing.
Docusaurus of VuePress zijn gebruikelijke keuzes in deze situaties. Ze zijn goed, maar ze halen een hele zee aan npm-pakketten binnen. Als je Node.js in je build-pijplijn wilt vermijden en snelle generatie waardeert, is het de moeite waard om naar het Hugo Book-thema van Alexander Shpak te kijken.
Wat dit thema is en voor wie het bedoeld is
Hugo Book is een minimalistische template voor de Hugo static site generator, gestileerd als een gewoon boek met een zijmenu. De projectauteur, Alexander Shpak, had een duidelijk doel: een schoon ontwerpthema creëren dat snel werkt en gebruikers niet dwingt uren door configuratiebestanden te graven.
De repository heeft meer dan 4.000 sterren verzameld op GitHub, wat best respectabel is voor een gespecialiseerd Hugo-thema. De template pakt standaard Markdown op en bouwt automatisch een boomstructuur van pagina's op basis van folder-nesting.
Belangrijkste functies onder de motorkap
In tegenstelling tot veel moderne webtools houdt Hugo Book zich aan een strikt dieet. De belangrijkste sitefunctionaliteit werkt volledig zonder JavaScript. Het omschakelen van het mobiele menu, het uitklappen van geneste secties en boomnavigatie worden allemaal gedaan in puur CSS.
Praktische functies zijn onder andere:
- Ingebouwd donker thema. Het past zich automatisch aan de instellingen van het besturingssysteem aan, maar je kunt ook een handmatige schakelaar toevoegen.
- Meertalige ondersteuning out of the box. Hugo kan parallelle folderstructuren voor verschillende talen beheren, en het thema rendert correct een versieschakelaar.
- Handige ingebouwde shortcodes. Voor het stylen van notities, waarschuwingen, mooie knoppen en code-tabs hoef je geen eigen workarounds te verzinnen.
- Ingebouwde zoekfunctie en reacties. Zoeken kan worden geïmplementeerd via een ingebouwd lichtgewicht script (FlexSearch) of diensten van derden.
Het principe van minimale interventie
De auteur merkt specifiek op in de projectfilosofie: het thema mag niet interfereren met gebruikerslay-outs of de configuratie overbelasten. Om een site te lanceren, hoef je letterlijk geen specifieke parameters in te stellen in config.toml of hugo.toml. De template pakt Hugo's standaard inhoudsstructuur op.
Als je aangepaste stijlen nodig hebt, kun je CSS in een paar regels overschrijven via een speciaal extensiebestand, zonder de broncode van het thema aan te raken. Dit bespaart je onderhoudshoofdpijn wanneer het thema over een paar maanden update.
Snelle start
Je hebt de uitgebreide versie van Hugo (Hugo extended) versie 0.158 of hoger geïnstalleerd nodig. Het installatieproces duurt twee minuten.
De eenvoudigste weg is om de kant-en-klare starter-repository te gebruiken:
git clone https://github.com/alex-shpak/hugo-book-starter my-docs
cd my-docs
git submodule update --init --remote
hugo server --minify
Na het starten van de lokale server op http://localhost:1313 wordt een kant-en-klare documentatiesite geopend. Wanneer je Markdown-bestanden wijzigt, werkt Hugo de pagina in de browser bijna direct. De bouwtijd voor sites met een paar honderd pagina's overschrijdt meestal niet een fractie van een seconde.
Shortcodes voor tekstlay-out
Standaard Markdown kan te beperkt zijn wanneer je een belangrijke notitie wilt markeren of kolommen wilt maken. Hugo Book heeft een set ingebouwde shortcodes.
De hint-shortcode wordt bijvoorbeeld gebruikt voor mooie informatieblokken:
{{< hint info >}}
Здесь можно написать полезную подсказку для читателя.
{{< /hint >}}
{{< hint warning >}}
А так оформляется предупреждение о возможных ошибках.
{{< /hint >}}
En als je codevoorbeelden voor verschillende besturingssystemen of programmeertalen wilt tonen, is de tabs-shortcode handig:
{{< tabs "unique-id" >}}
{{< tab "Linux" >}}
sudo apt install my-tool
{{< /tab >}}
{{< tab "macOS" >}}
brew install my-tool
{{< /tab >}}
{{< /tabs >}}
Versiebeheerbenadering
Het thema wordt gedistribueerd onder de MIT-licentie. De auteur gebruikt incrementele versiebeheer (bijv. v0.13.0, v0.14.0). Breaking changes tussen releases komen af en toe voor, dus voor productie is het beter om vast te pinnen aan een specifieke tag in plaats van op de main-branch te blijven.
Waar dit van pas komt
Het thema is perfect voor:
- Technische documentatie voor open source-bibliotheken
- Interne teamkennisbank of bedrijfs-Wiki
- Service-implementatie en API-instructies
- Persoonlijke technische blog of notitiecollectie
Als je zware interactiviteit, 3D-graphics direct in de documentatie of diepe integratie met React-componenten nodig hebt, is Hugo Book waarschijnlijk niet geschikt. In dat geval moet je kijken naar Docusaurus of Astro Starlight. Maar voor typische documentatietaken is de eenvoud van Hugo Book meer dan voldoende.
Valkuilen
Met alle voordelen moet je de nuances van Hugo's infrastructuur begrijpen. De Go HTML Templates-templating engine die Hugo onderliggt heeft een specifieke syntaxis. Als je de header- of footerstructuur radicaal wilt herschrijven, moet je tijd investeren in het leren van de Go-templatesstructuur.
Bovendien wordt de zoekindex voor lokale zoekopdrachten gegenereerd tijdens het bouwen. Voor enorme sites met tienduizenden pagina's kan het zoekbestand groot worden, hoewel dit voor typische handleidingen helemaal geen probleem is.
De conclusie
Hugo Book is een eerlijk tool zonder onnodige opsmuk. Het doet precies wat het belooft: het verandert een hoop folders met Markdown in een snelle, schone en leesbare site. Geen npm-pakketten om te installeren, geen lange bouwprocessen en geen complexe configuratie.
Gerelateerde projecten