Jak zbudować czystą dokumentację bez gigabajtów node_modules
Kiedy rozpoczynasz nowy projekt lub utrzymujesz bibliotekę w zespole, pytanie o podstawową dokumentację nieuchronnie się pojawia. Załóżmy, że nie potrzebujesz potwornie dużego portalu z dynamicznym routingiem, reaktywnymi komponentami i setkami megabajtów zależności. Chcesz po prostu napisać kilka plików Markdown, nacisnąć przycisk i otrzymać czystą stronę z nawigacją drzewiastą, wyszukiwaniem i adaptacją mobilną.
Docusaurus lub VuePress to popularne wybory w takich sytuacjach. Są dobre, ale wciągają całą masę pakietów npm. Jeśli chcesz uniknąć Node.js w swoim pipeline budowania i cenisz błyskawiczną generację, warto przyjrzeć się motywowi Hugo Book autorstwa Alexandra Shpaka.
Co to za motyw i dla kogo jest przeznaczony
Hugo Book to minimalistyczny szablon dla statycznego generatora stron Hugo, stylizowany jak zwykła książka z bocznym menu. Autor projektu, Alexander Shpak, miał jasny cel: stworzyć czysty motyw projektowy, który działa szybko i nie zmusza użytkowników do spędzania godzin na przekopywaniu się przez pliki konfiguracyjne.
Repozytorium zgromadziło ponad 4000 gwiazdek na GitHub, co jest całkiem szanowane dla wyspecjalizowanego motywu Hugo. Szablon rozpoznaje standardowy Markdown i automatycznie buduje strukturę drzewiastą stron na podstawie zagnieżdżenia folderów.
Kluczowe funkcje pod maską
W przeciwieństwie do wielu nowoczesnych narzędzi webowych, Hugo Book trzyma się ścisłej diety. Główna funkcjonalność strony działa całkowicie bez JavaScript. Przełączanie menu mobilnego, rozwijanie zagnieżdżonych sekcji i nawigacja drzewiasta są wykonywane w czystym CSS.
Do praktycznych funkcji należą:
- Wbudowany motyw ciemny. Automatycznie dostosowuje się do ustawień systemu operacyjnego, ale można też dodać ręczny przełącznik.
- Wielojęzyczne wsparcie out of the box. Hugo może zarządzać równoległymi strukturami folderów dla różnych języków, a motyw poprawnie renderuje przełącznik wersji.
- Wygodne wbudowane shortcodes. Do stylizowania notatek, ostrzeżeń, ładnych przycisków i zakładek kodu nie musisz wymyślać własnych obejść.
- Wbudowane wyszukiwanie i komentarze. Wyszukiwanie może być zaimplementowane poprzez wbudowany lekki skrypt (FlexSearch) lub usługi stron trzecich.
Zasada minimalnej interwencji
Autor specjalnie podkreśla w filozofii projektu: motyw nie powinien ingerować w układy użytkowników ani przeciążać konfiguracji. Aby uruchomić stronę, dosłownie nie musisz ustawiać żadnych konkretnych parametrów w config.toml lub hugo.toml. Szablon przejmuje standardową strukturę treści Hugo.
Jeśli potrzebujesz niestandardowych stylów, możesz nadpisać CSS w kilku linijkach poprzez specjalny plik rozszerzenia, bez dotykania kodu źródłowego motywu. To oszczędza Ci bólu głowy związanego z konserwacją, gdy motyw zaktualizuje się za kilka miesięcy.
Szybki start
Będziesz potrzebować rozszerzonej wersji Hugo (Hugo extended) w wersji 0.158 lub wyższej. Proces konfiguracji trwa dwie minuty.
Najprostsza ścieżka to użycie gotowego repozytorium startowego:
git clone https://github.com/alex-shpak/hugo-book-starter my-docs
cd my-docs
git submodule update --init --remote
hugo server --minify
Po uruchomieniu lokalnego serwera pod adresem http://localhost:1313 otworzy się gotowa strona dokumentacji. Gdy modyfikujesz pliki Markdown, Hugo aktualizuje stronę w przeglądarce niemal natychmiast. Czas budowania dla stron z kilkoma setkami stron zwykle nie przekracza ułamka sekundy.
Shortcodes do układu tekstu
Standardowy Markdown może być zbyt ograniczony, gdy chcesz wyróżnić ważną notatkę lub utworzyć kolumny. Hugo Book ma zestaw wbudowanych shortcodes.
Na przykład shortcode hint służy do tworzenia ładnych bloków informacyjnych:
{{< hint info >}}
Здесь можно написать полезную подсказку для читателя.
{{< /hint >}}
{{< hint warning >}}
А так оформляется предупреждение о возможных ошибках.
{{< /hint >}}
A jeśli potrzebujesz pokazać przykłady kodu dla różnych systemów operacyjnych lub języków programowania, przydaje się shortcode tabs:
{{< tabs "unique-id" >}}
{{< tab "Linux" >}}
sudo apt install my-tool
{{< /tab >}}
{{< tab "macOS" >}}
brew install my-tool
{{< /tab >}}
{{< /tabs >}}
Podejście do wersjonowania
Motyw jest dystrybuowany na licencji MIT. Autor używa przyrostowego wersjonowania (np. v0.13.0, v0.14.0). Przełomowe zmiany między wydaniami zdarzają się sporadycznie, więc dla produkcji lepiej jest przypiąć do konkretnego tagu niż pozostać na gałęzi głównej.
Gdzie to się przyda
Motyw świetnie sprawdza się przy:
- Dokumentacji technicznej bibliotek open source
- Wewnętrznej bazie wiedzy zespołu lub korporacyjnej Wiki
- Instrukcjach wdrażania usług i API
- Osobistym blogu inżynierskim lub kolekcji notatek
Jeśli potrzebujesz ciężkiej interaktywności, grafik 3D bezpośrednio w dokumentacji lub głębokiej integracji z komponentami React, Hugo Book prawdopodobnie nie będzie odpowiedni. W takim przypadku będziesz musiał szukać w kierunku Docusaurus lub Astro Starlight. Ale do typowych zadań dokumentacyjnych prostota Hugo Book jest więcej niż wystarczająca.
Podwodne kamienie
Przy wszystkich zaletach musisz zrozumieć niuanse infrastruktury Hugo. Silnik szablonów HTML Go, który leży u podstaw Hugo, ma specyficzną składnię. Jeśli chcesz radykalnie przepisać strukturę nagłówka lub stopki, będziesz musiał poświęcić czas na naukę struktury szablonów Go.
Ponadto indeks wyszukiwania dla wyszukiwania lokalnego jest generowany w czasie budowania. W przypadku ogromnych stron z dziesiątkami tysięcy stron plik wyszukiwania może być spory, choć dla typowych poradników w ogóle nie stanowi to problemu.
Podsumowując
Hugo Book to uczciwe narzędzie bez zbędnego lukru. Robi dokładnie to, co obiecuje: zamienia stos folderów z Markdown w szybką, czystą i czytelną stronę. Bez pakietów npm do zainstalowania, bez długich budowań i bez skomplikowanej konfiguracji.
Powiązane projekty