Deep Dive: Hugo – co robi generator stron statycznych, co zastąpiło moje wtyczki WordPressa i jak działa wyszukiwanie bez serwera

Czym jest Hugo i czym różni się od WordPressa, co przejęło zadania Yoast, Polylang i wtyczek cache, jak działa pole wyszukiwania na stronie bez serwera, jak dodaję wpis i aktualizuję Hugo – i które pułapki wyszły dopiero w eksploatacji.

Mały robot na taśmie produkcyjnej zamienia strony Markdown w gotowe strony HTML i nakleja na nie etykiety SEO, monitor pokazuje Markdown → Hugo → HTML

🌐 Także w: English · Deutsch · Français · Español · Italiano · Português · Nederlands

Deep Dive z serii wokół Ansible Tour. Tour objaśnia role, deep dive’y – technikę pod spodem: jak działa, dlaczego jest tu używana właśnie tak i co po drodze poszło nie tak.

Na początku listopada ten blog przeniósł się z WordPressa na Kubernetesie na Hugo. O eksperymencie z prawdziwymi liczbami i o samej przeprowadzce piszę gdzie indziej. Ten wpis to przegląd, który sam chciałbym mieć przed startem: czym właściwie jest Hugo, co przejęło zadania wtyczek WordPressa, jak działa pole wyszukiwania na stronie, która nie ma w ogóle kodu po stronie serwera, co robię, gdy dodaję wpis albo aktualizuję Hugo, i gdzie mnie zaskoczył.

Spis treści

🧭 Czym jest Hugo

Drukarnia zamiast kuchni

WordPress działa jak kuchnia w restauracji: za każdym razem, gdy gość coś zamawia, PHP gotuje stronę z bazy danych – chyba że wtyczka cache ma już gotowy talerz. Hugo działa jak drukarnia: drukuje każdą stronę raz, z wyprzedzeniem, a serwer WWW tylko wydaje gotowe egzemplarze. Kiedy przychodzi czytelnik, nic się nie gotuje.

Technicznie Hugo to static site generator: jeden program napisany w Go, który czyta pliki Markdown, szablony i obrazy, a zapisuje folder pełen HTML, CSS, obrazów i feedów. Ten folder to strona. Może go serwować dowolny serwer WWW; tutaj to zwykły nginx.

Jedna binarka, dwie edycje

Hugo to jeden plik wykonywalny bez zależności – bez PHP, bez bazy danych, bez Node.js. Występuje w edycji standardowej i extended; ta druga dodaje kodowanie WebP i Sass. Ten blog używa edycji extended, wersji 0.169.0, bo każdy obraz jest podczas builda skalowany i konwertowany do WebP.

Wniosek: Hugo przenosi całą pracę z chwili wizyty na chwilę publikacji. Cała reszta tego wpisu z tego wynika.

⚖️ Hugo kontra WordPress

PytanieWordPressHugo
Kiedy powstaje strona?Przy każdym żądaniu (albo z cache)Raz, podczas builda
Co działa na serwerze?PHP, MariaDB, często RedisTylko serwer WWW
Powierzchnia atakuLogowanie, admin, wtyczki, XML-RPC, PHPPliki statyczne
Regularne aktualizacjeCore, wtyczki, motywy, PHPnginx; Hugo tylko na maszynie buildowej
Gdzie piszę?Edytor w przeglądarceEdytor tekstu, Git
Komentarze, formularzeWbudowanePotrzebna zewnętrzna usługa
SzybkośćZ cache: 58 ms dla strony głównej57 ms – bez różnicy
Waga strony (główna, bez obrazów)25 plików, 198 KB3 pliki, 9,5 KB

Liczby pochodzą z moich własnych pomiarów sprzed przeprowadzki. Szybkość nie była powodem: dobrze scache’owany WordPress jest równie szybki. Powodami była reszta tabeli – brak logowania do atakowania, brak cotygodniowych aktualizacji wtyczek, brak bazy danych do backupu i strona mniejsza o 95 %.

Z czego zrezygnowałem: z edytora w przeglądarce, z komentarzy i z wygody instalowania funkcji jednym kliknięciem.

Wniosek: WordPress to program, który produkuje stronę. Hugo produkuje stronę raz i usuwa się z drogi. Czy to lepsze, zależy od tego, czy potrzebujesz czegoś, co potrafi tylko działający program.

🔧 Jak działa Hugo

Treść: Markdown z front matter

Każdy wpis to plik Markdown. Na górze jest front matter, blok YAML, który Hugo czyta jako dane. Wpis na tym blogu zaczyna się tak:

---
title: 'Zabbix in Containers Watches My Home Network'
slug: zabbix-in-containers-watches-my-home-network
date: '2026-11-13T15:40:00+01:00'
translationKey: zabbix-heimnetz-2026-11
description: 'Short summary for search results, at most about 155 characters.'
categories:
- linux
tags:
- zabbix
image: uploads/2026/11/zabbix-watchman.webp
imageAlt: What the picture shows, for screen readers and search engines
---

Pod drugim --- zaczyna się tekst. Markdown obsługuje nagłówki, listy, tabele i kod; tam, gdzie to nie wystarcza, dozwolony jest surowy HTML (unsafe = true w ustawieniach Goldmarka), co ma znaczenie dla wpisów przekonwertowanych z WordPressa.

Foldery, sekcje i adresy

site/
├── content/en/posts/   posts in English (one folder per language)
├── content/de/posts/   posts in German, and so on for eight languages
├── layouts/            templates: the theme
├── assets/             CSS and JavaScript, processed by Hugo
├── uploads/            images and downloads
├── i18n/               interface words per language ("Read more", "Search")
├── data/               menus, flags, footer text as JSON
└── hugo.toml           configuration

hugo.toml decyduje o adresach: posts = "/:year/:month/:day/:slug/" zachowuje schemat URL-i, którego używał WordPress, więc żaden stary link się nie zepsuł. Kategorie i tagi to taxonomies; Hugo sam buduje stronę dla każdej kategorii i każdego tagu.

Szablony

Szablony używają języka szablonów Go. baseof.html to rama każdej strony, page.html pojedynczy wpis, home.html strona główna, a partials to elementy wielokrotnego użytku – nagłówek, sidebar, <head> ze wszystkimi meta tagami. Nie używam gotowego motywu: layouty zostały napisane tak, żeby wyglądały jak stary motyw WordPressa.

Pipeline zasobów

Hugo sam przetwarza pliki: resources.Get "css/main.css" | minify | fingerprint minifikuje arkusz stylów i wstawia hash do nazwy pliku, dzięki czemu przeglądarki mogą go cache’ować na zawsze. Obrazy są skalowane podczas builda – na przykład obraz podglądu dla mediów społecznościowych powstaje z obrazu wpisu w rozdzielczości 1200 px i jest zmniejszany, aż zejdzie poniżej 280 KB, czyli limitu dla podglądów w WhatsAppie.

Wielojęzyczność od początku

Każdy język ma w hugo.toml własny folder treści, etykietę i locale. Wpisy, które do siebie należą, mają wspólny translationKey; dzięki niemu Hugo zna tłumaczenia każdej strony i buduje przełącznik języka oraz linki hreflang. Ten blog ma teraz osiem języków – angielski, niemiecki, francuski, hiszpański, włoski, portugalski, niderlandzki i polski.

Podgląd i szkice

hugo server buduje stronę w pamięci i serwuje ją na localhost:1313; każdy zapisany plik przeładowuje przeglądarkę. draft: true trzyma wpis poza prawdziwym buildem, podobnie jak data w przyszłości – o tym więcej niżej.

Wniosek: treść, szablony i konfiguracja to trzy osobne rodzaje plików. Możesz zmienić wygląd, nie dotykając ani jednego wpisu, i napisać wpis, nie wiedząc, jak działają szablony.

🧩 Gdzie podziały się wtyczki

W WordPressie prawie każda funkcja była wtyczką. W Hugo funkcja jest albo wbudowana, albo jest kilkoma liniami szablonu, albo małym skryptem uruchamianym po buildzie.

Wtyczka WordPressaZadanieTeraz
Yoast SEOTytuł, description, canonical, Open Graph, dane strukturalnehead.html (jeden szablon dla wszystkich stron)
Yoast SEOSitemapWbudowana w Hugo, własny szablon sitemap.xml z hreflang
Yoast SEO„Twój wpis nie ma description”check_posts.py: build się zatrzymuje
PolylangJęzyki, przełącznik językaWbudowane w Hugo
CompressXObrazy WebP, mniejsze rozmiaryPrzetwarzanie obrazów w Hugo
AutoptimizeMinifikacja CSS, JS, HTMLhugo --minify
WP Super Cache, RedisCache stron i obiektówNiepotrzebny – każda strona już jest plikiem
Wyszukiwanie (WordPress)Wyszukiwanie pełnotekstowePagefind (następna sekcja)

SEO bez wtyczki

Yoast robił trzy rzeczy: pisał meta tagi, budował sitemap i marudził. Dwie pierwsze to teraz jeden partial, head.html. Dla każdej strony zapisuje tytuł (albo krótszy seoTitle z front matter), description, link canonical, jeden link hreflang na tłumaczenie, tagi Open Graph i Twitter z wygenerowanym obrazem podglądu, daty artykułu oraz blok JSON-LD z tymi samymi danymi strukturalnymi, które produkował Yoast (Article, WebPage, BreadcrumbList, Person). To jeden plik i jest taki sam dla każdej strony – żadnego ekranu ustawień dla każdego wpisu.

Marudzenie przeniosło się do builda: tools/check_posts.py zatrzymuje build, jeśli wpisowi brakuje tytułu, description, obrazu, tekstu obrazu, klucza tłumaczenia albo daty, albo jeśli plik obrazu nie istnieje, i ostrzega, gdy description robi się za długi albo brakuje tłumaczenia.

Rozszerzenia w Hugo

Hugo nie ma sklepu z wtyczkami, ale ma punkty rozszerzeń:

  • Motywy i Hugo Modules – kompletne wyglądy albo ich części, dociągane jak zależność. Ten blog montuje własne foldery przez module.mounts (folder uploadów jest montowany dwa razy: raz do przetwarzania obrazów, raz jako /wp-content/uploads/, żeby stare adresy obrazów dalej działały).
  • Shortcodes – małe szablony, które wywołujesz z Markdowna, np. dla wideo albo ramki z komunikatem.
  • Render hooks – twój własny szablon dla każdego linku, obrazu czy nagłówka, który generuje Markdown.
  • Formaty wyjściowe – ta sama treść jako HTML, RSS, JSON albo cokolwiek innego.
  • Narzędzia po buildzie – build to tylko folder, więc może na nim pracować dowolny program. Tutaj imgattrs.py dodaje srcset i lazy loading do obrazów w starych wpisach, a Pagefind buduje indeks wyszukiwania.

Wniosek: większość wtyczek rozwiązywała problemy, których strona statyczna nie ma. Reszta stała się szablonem albo skryptem, który mogę przeczytać w całości – co oznacza też, że nikt inny nie aktualizuje ich za mnie.

🔍 Jak działa wyszukiwanie bez serwera

Pole wyszukiwania wydaje się potrzebować serwera: ktoś przecież musi wyszukać słowa. Pagefind przenosi także tę pracę do builda.

  1. Podczas builda Pagefind czyta każdą gotową stronę HTML. Indeksuje tylko część oznaczoną data-pagefind-body (artykuł), więc menu i sidebary nie zaśmiecają wyników, i pomija wszystko, co oznaczono data-pagefind-ignore. Język rozpoznaje po atrybucie lang i buduje jeden indeks na język.
  2. Indeks jest podzielony na wiele małych plików w /pagefind/ – łącznie 18 MB dla ośmiu języków. Nikt nie pobiera całości.
  3. W przeglądarce nic się nie ładuje, dopóki ktoś faktycznie nie zacznie szukać. Wtedy kilka linii JavaScriptu importuje Pagefind, który pobiera tylko fragmenty indeksu dla wpisanych słów i fragmenty pasujących stron, a potem pokazuje tytuł i wycinek.
import('/pagefind/pagefind.js')
  .then(function (m) { return m.search(term); })
  .then(function (r) { return Promise.all(r.results.slice(0, 8).map(function (x) { return x.data(); })); })

Efekt uboczny, który lubię: szukana fraza nigdy nie trafia do serwera jako query string, więc nie ląduje w access logu. Formularz jest celowo ukryty dla przeglądarek bez JavaScriptu – zwykłe wysłanie formularza wstawiłoby frazę do URL-a.

Wniosek: „statyczny” nie znaczy „bez interakcji”. Znaczy, że interakcja odbywa się w przeglądarce czytelnika, na danych przygotowanych z wyprzedzeniem.

✍️ Mój workflow dla nowego wpisu

  1. Napisać plik Markdown w site/content/en/posts/<slug>.md z front matter jak wyżej. Tłumaczenia dostają tę samą nazwę pliku, ten sam translationKey i tagi z sufiksem języka (hugo-de, hugo-fr, …).
  2. Dodać obraz do site/uploads/YYYY/MM/ – WebP, maksymalnie 1536 px szerokości, poniżej 280 KB. W tekście obrazy są podawane jako /wp-content/uploads/YYYY/MM/name.webp, czyli adres, którego używał WordPress.
  3. Build:
tools/build.sh

Uruchamia check_posts.py, potem hugo --gc --minify, potem imgattrs.py, potem Pagefind. Samo Hugo potrzebuje około dziesięciu sekund na całą stronę.

  1. Opublikować:
tools/deploy.sh <host> 10022

rsync wysyła build do folderu incoming/; serwer kopiuje go potem do nowego folderu release’u i jednym krokiem przestawia na niego symlink. Pięć ostatnich release’ów zostaje, więc tools/deploy.sh <host> 10022 rollback cofa wszystko w sekundę. Klucz deployu nie może nic więcej – serwer akceptuje dla niego dokładnie te polecenia i żadnych innych.

  1. Commit i push repozytorium z treścią.

Dwa repozytoria: otwarty kod, prywatna treść

Serwer i narzędzia buildowe są w publicznym repozytorium, www_hugo, obok kodu Ansible dla całej reszty. Treść – wpisy, obrazy, szablony, szkice – jest w prywatnym. Powód jest taki, że repozytorium pamięta wszystko: obraz, który zdejmuję ze strony, zostałby na zawsze w historii publicznego repo, a szkice nie są przeznaczone dla czytelników. Serwer dostaje tylko gotowe pliki przez krok deployu i nigdy nie widzi szkicu; publiczne repo w ogóle nie widzi treści.

Wniosek: publikacja to dwa niezależne kroki. Serwer pokazuje to, co zostało ostatnio zdeployowane, Git przechowuje to, co zostało ostatnio zacommitowane – robię jedno i drugie, w tej kolejności.

⬆️ Aktualizacja Hugo

Hugo w ogóle nie jest zainstalowane na serwerze. Żyje jako jedna binarka w .tools/ na maszynie, która buduje stronę, razem z Pagefindem. Wersje są przypięte w versions.yml publicznego repo:

hugo_version:                "0.169.0"   # github.com/gohugoio/hugo/releases
pagefind_version:            "1.6.0"     # github.com/Pagefind/pagefind/releases

Aktualizacja idzie według tego samego schematu co wszystko inne tutaj:

  1. Przeczytać release notes – Hugo co jakiś czas oznacza funkcje szablonów jako przestarzałe i ostrzega o nich w wyjściu builda długo przed ich usunięciem.
  2. Pobrać release extended dla Linuksa, porównać jego SHA-256 z plikiem sum kontrolnych release’u, podmienić .tools/hugo.
  3. Zbudować do osobnego folderu i porównać z poprzednim buildem (diff -r). Powinny pojawić się tylko oczekiwane różnice.
  4. Zmienić pin w versions.yml, deploy, commit.

Ponieważ serwer tylko serwuje pliki, aktualizacja Hugo nigdy nie zepsuje działającej strony. Najgorszy przypadek to build, który się wywala albo wygląda inaczej – a to dzieje się na mojej maszynie, nie na oczach czytelników.

Wniosek: generator to narzędzie buildowe, jak kompilator. Przypnij wersję, aktualizuj świadomie i porównuj wynik.

🤖 Co Claude robi wokół Hugo

Większość pracy nad tym blogiem robię razem z Claude (AI od Anthropic) w terminalu. W podziale na tematy:

  • Migracja: eksport z WordPressa, konwersja każdego wpisu do Markdowna z front matter, zachowane stare adresy i ścieżki obrazów, przekierowania dla zmienionych slugów.
  • Szablony i wygląd: odtworzenie starego motywu w szablonach Hugo, slider, sidebar, ciemne zakamarki w rodzaju stron archiwum według daty.
  • SEO: partial head.html, sitemap z hreflang, dane strukturalne, obrazy podglądu poniżej limitu WhatsAppa.
  • Pisanie i tłumaczenie: szkice moimi słowami, tłumaczenia na wszystkie osiem języków według stałych reguł (bloki kodu identyczne co do bajtu, linki przepisane dla każdego języka) i checker, który porównuje każde tłumaczenie z angielskim oryginałem.
  • Kontrole: kontrola w buildzie, sprawdzanie linków na wszystkich wygenerowanych stronach, kontrola na żywo działającej strony.
  • Serwer i deploy: rola Ansible dla nginx, atomowy deploy, SELinux, monitoring.
  • Troubleshooting: ustalenie, dlaczego wpis się nie pojawił (patrz następna sekcja) albo dlaczego breadcrumb wskazywał na nieistniejącą stronę.

Co zostaje przy mnie: decyzja, co jest pisane i publikowane, czytanie każdego szkicu, uruchamianie playbooków oraz każdy push i deploy – Claude pyta przed każdym z nich.

Wniosek: strona statyczna to pliki tekstowe i małe skrypty – dokładnie ten materiał, z którym asystent AI dobrze sobie radzi. Decyzje dalej należą do mnie.

🐛 Pułapki, które wyszły dopiero w eksploatacji

  1. Wpis z przyszłości nie jest budowany. Ustawiłem datę wpisu na 15:50, a build zrobiłem o 15:44 – Hugo po cichu go pominął. Żadnego błędu, wpisu po prostu nie było. date musi być w przeszłości, albo build potrzebuje --buildFuture.
  2. Brakująca strona dnia. Breadcrumb nowego wpisu linkował do archiwum jego dnia (/2026/11/13/), które nie istniało, bo strony dat są plikami treści, a nie stronami generowanymi. Sprawdzanie linków to wyłapało; teraz nowa data potrzebuje własnego _index.md. A podczas pisania właśnie tego wpisu oba błędy zdarzyły się znowu: wpis miał datę 08:30, a build był o 08:22, a jego nowa strona dnia miała 12:00 – strona z datą w południe jest w przyszłości przez cały poranek.
  3. Przekonwertowany HTML jest kruchy. Wpisy zaimportowane z WordPressa to mieszanka Markdowna i surowego HTML-a. W kilku z nich słowa były sklejone albo przetrwała zabłąkana **. Znalazła je dopiero kontrola wyrenderowanych stron we wszystkich językach.
  4. Ustawienia typografii mają znaczenie. Typographer Hugo domyślnie zamienia -- na myślnik. WordPress tego nie robił, więc polecenia takie jak --check w starych wpisach zmieniłyby się w –check. Ustawienie dotyka teraz tylko cudzysłowów i apostrofów.
  5. Nie wszystko powinno trafić do wyszukiwania i feedów. Impressum i polityka prywatności zawierają adres pocztowy. Mają noindex, są wyłączone z feedów RSS i z indeksu Pagefind – wtyczka potrzebowałaby do każdej z tych rzeczy osobnego ustawienia, tutaj to jeden warunek w szablonach.
  6. Niektóre adresy pochodzą z front matter. Kilka starych wpisów ma klucz url: z pełną ścieżką. W tłumaczeniach potrzebuje on prefiksu języka, inaczej wszystkie języki zgłaszają ten sam adres.

Wniosek: Hugo robi dokładnie to, co mu każesz, i rzadko narzeka. Kontrole, które wtyczki WordPressa robiły po cichu, trzeba spisać – a potem działają przy każdym buildzie.

📊 Zmierzone

Wpisy146, w 8 językach
Wygenerowane strony HTMLokoło 23 000 (wpisy, tagi, kategorie, archiwa)
Build Hugookoło 10 s (cała strona)
Folder wyjściowy498 MB, prawie same obrazy
Indeks wyszukiwania18 MB dla 8 języków, ładowany małymi kawałkami
Oprogramowanie na serwerze dla bloganginx

🎯 Wnioski

  • Zdecyduj, gdzie odbywa się praca: przy wizycie (WordPress) czy przy publikacji (Hugo).
  • Zanim zastąpisz wtyczkę, sprawdź, co naprawdę robiła – większość to jeden szablon, część to kontrola, którą musisz napisać sam.
  • Wyszukiwanie, feedy i sitemapy działają bez serwera, gdy build przygotuje dane.
  • Przypinaj wersję generatora jak każdego innego narzędzia buildowego i porównuj wynik przed deployem.
  • Brakujący wpis bez żadnego komunikatu o błędzie to zwykle data w przyszłości.
  • Trzymaj treść i kod osobno, gdy kod jest publiczny.
Część tekstów i obrazów na tej stronie powstała z pomocą AI lub została wygenerowana przez AI. Szczegóły