So erstellst du saubere Dokumentation ohne Gigabytes an node_modules
Wenn du ein neues Projekt startest oder eine Bibliothek in einem Team pflegst, kommt unweigerlich die Frage nach einer grundlegenden Dokumentation auf. Nehmen wir an, du brauchst kein riesiges Portal mit dynamischem Routing, reaktiven Komponenten und Hunderten von Megabytes an Abhängigkeiten. Du möchtest einfach ein paar Markdown-Dateien schreiben, einen Button drücken und eine saubere Seite mit Baum-Navigation, Suche und mobiler Anpassung erhalten.
Docusaurus oder VuePress sind in solchen Situationen gängige Entscheidungen. Sie sind gut, aber sie ziehen eine ganze Flut an npm-Paketen mit sich. Wenn du Node.js in deiner Build-Pipeline vermeiden und blitzschnelle Generierung schätzen möchtest, lohnt sich ein Blick auf das Hugo Book Theme von Alexander Shpak.
Was dieses Theme ist und für wen es gedacht ist
Hugo Book ist eine minimalistische Vorlage für den Hugo Static-Site-Generator, gestaltet wie ein gewöhnliches Buch mit einem Seitenmenü. Der Projektautor Alexander Shpak hatte ein klares Ziel: ein sauberes Design-Theme zu erstellen, das schnell funktioniert und die Nutzer nicht zwingt, stundenlang Konfigurationsdateien zu durchsuchen.
Das Repository hat über 4.000 Sterne auf GitHub gesammelt, was für ein spezialisiertes Hugo-Theme ziemlich respektabel ist. Die Vorlage erkennt Standard-Markdown und baut automatisch eine Baumstruktur der Seiten basierend auf der Ordner-Verschachtelung auf.
Wichtige Funktionen unter der Haube
Im Gegensatz zu vielen modernen Web-Tools hält sich Hugo Book an eine strenge Diät. Die Hauptfunktionalität der Seite funktioniert komplett ohne JavaScript. Mobile Menü-Umschaltung, das Aufklappen verschachtelter Abschnitte und die Baum-Navigation werden allesamt in reinem CSS umgesetzt.
Praktische Funktionen umfassen:
- Integriertes Dark Theme. Es passt sich automatisch an die Einstellungen des Betriebssystems an, aber du kannst auch einen manuellen Umschalter hinzufügen.
- Mehrsprachige Unterstützung out of the box. Hugo kann parallele Ordnerstrukturen für verschiedene Sprachen verwalten, und das Theme rendert korrekt einen Sprachumschalter.
- Praktische eingebaute Shortcodes. Für das Styling von Notizen, Warnungen, schönen Buttons und Code-Tabs brauchst du keine eigenen Workarounds.
- Integrierte Suche und Kommentare. Die Suche kann über ein eingebautes leichtgewichtiges Script (FlexSearch) oder Drittanbieter-Dienste implementiert werden.
Das Prinzip der minimalen Eingriffe
Der Autor betont in der Projektphilosophie ausdrücklich: Das Theme sollte nicht in die Layouts der Nutzer eingreifen oder die Konfiguration überladen. Um eine Seite zu starten, brauchst du buchstäblich keine bestimmten Parameter in config.toml oder hugo.toml setzen. Die Vorlage erkennt Hugos Standard-Inhaltsstruktur.
Wenn du eigene Styles brauchst, kannst du CSS in ein paar Zeilen über eine spezielle Erweiterungsdatei überschreiben, ohne den Quellcode des Themes zu berühren. Das erspart dir Wartungskopfschmerzen, wenn das Theme in ein paar Monaten ein Update bekommt.
Schneller Einstieg
Du brauchst die Extended-Version von Hugo (Hugo extended) Version 0.158 oder höher. Der Einrichtungsprozess dauert zwei Minuten.
Der einfachste Weg ist das fertige Starter-Repository zu verwenden:
git clone https://github.com/alex-shpak/hugo-book-starter my-docs
cd my-docs
git submodule update --init --remote
hugo server --minify
Nach dem Start des lokalen Servers unter http://localhost:13 öffnet sich eine fertige Dokumentationsseite. Wenn du Markdown-Dateien änderst, aktualisiert Hugo die Seite im Browser fast sofort. Die Build-Zeit für Seiten mit ein paar hundert Seiten überschreitet normalerweise nicht einen Bruchteil einer Sekunde.
Shortcodes für das Text-Layout
Standard-Markdown kann zu eingeschränkt sein, wenn du eine wichtige Notiz hervorheben oder Spalten erstellen musst. Hugo Book hat eine Reihe eingebauter Shortcodes.
Der Hint-Shortcode wird zum Beispiel für schöne Info-Blöcke verwendet:
{{< hint info >}}
Здесь можно написать полезную подсказку для читателя.
{{< /hint >}}
{{< hint warning >}}
А так оформляется предупреждение о возможных ошибках.
{{< /hint >}}
Und wenn du Code-Beispiele für verschiedene Betriebssysteme oder Programmiersprachen zeigen musst, kommt der Tabs-Shortcode zum Einsatz:
{{< tabs "unique-id" >}}
{{< tab "Linux" >}}
sudo apt install my-tool
{{< /tab >}}
{{< tab "macOS" >}}
brew install my-tool
{{< /tab >}}
{{< /tabs >}}
Versionsansatz
Das Theme wird unter der MIT-Lizenz vertrieben. Der Autor verwendet inkrementelle Versionierung (z.B. v0.13.0, v0.14.0). Breaking Changes zwischen Releases kommen gelegentlich vor, daher ist es für die Produktion besser, auf ein bestimmtes Tag zu pinnen statt auf dem Main-Branch zu bleiben.
Wo das nützlich ist
Das Theme eignet sich hervorragend für:
- Technische Dokumentation für Open-Source-Bibliotheken
- Interne Team-Wissensdatenbank oder Corporate Wiki
- Service-Deployment- und API-Anleitungen
- Persönlichen Engineering-Blog oder Notizsammlung
Wenn du schwere Interaktivität, 3D-Grafiken direkt in der Dokumentation oder tiefe Integration mit React-Komponenten brauchst, passt Hugo Book wahrscheinlich nicht. In diesem Fall solltest du dich nach Docusaurus oder Astro Starlight umsehen. Aber für typische Dokumentationsaufgaben ist die Einfachheit von Hugo Book mehr als ausreichend.
Fallstricke
Bei all den Vorteilen musst du die Feinheiten von Hugos Infrastruktur verstehen. Die Go HTML Templates-Templating-Engine, die Hugo zugrunde liegt, hat eine spezifische Syntax. Wenn du die Header- oder Footer-Struktur radikal umschreiben möchtest, musst du Zeit investieren, um die Go-Template-Struktur zu lernen.
Zusätzlich wird der Suchindex für die lokale Suche zur Build-Zeit generiert. Für riesige Seiten mit Zehntausenden von Seiten kann die Suchdatei ganz schön groß werden, obwohl das für typische Anleitungen überhaupt kein Problem darstellt.
Fazit
Hugo Book ist ein ehrliches Tool ohne überflüssigen Schnickschnack. Es macht genau das, was es verspricht: eine Reihe von Ordnern mit Markdown in eine schnelle, saubere und lesbare Seite verwandeln. Keine npm-Pakete zu installieren, keine langwierigen Builds und keine komplexe Konfiguration.
Ähnliche Projekte