Deep Dive: Hugo – wat een static site generator doet, wat mijn WordPress-plugins verving en hoe zoeken werkt zonder server
Wat Hugo is en hoe het verschilt van WordPress, wat de taken van Yoast, Polylang en de cacheplugins overnam, hoe een zoekveld werkt op een site zonder server, hoe ik een post toevoeg en Hugo update – en welke valkuilen pas in de praktijk opdoken.

🌐 Ook in: English · Deutsch · Français · Español · Italiano · Português · Polski
Deep Dive in de serie rond de Ansible Tour. De tour legt de roles uit, de deep dives de techniek eronder: hoe het werkt, waarom het hier zo wordt gebruikt en wat er onderweg misging.
Begin november verhuisde deze blog van WordPress op Kubernetes naar Hugo. Het experiment met echte cijfers en de verhuizing zelf staan elders beschreven. Deze post is het overzicht dat ik zelf had willen hebben voordat ik begon: wat Hugo eigenlijk is, wat de taken van de WordPress-plugins overnam, hoe een zoekveld werkt op een site zonder enige servercode, wat ik doe als ik een post toevoeg of Hugo update, en waar het me verraste.
Inhoud
🧭 Wat Hugo is
Een drukpers in plaats van een keuken
WordPress werkt als een restaurantkeuken: elke keer dat een gast bestelt, kookt PHP de pagina uit de database – tenzij een cacheplugin al een bord klaar heeft staan. Hugo werkt als een drukpers: het drukt elke pagina één keer, vooraf, en de webserver deelt alleen kant-en-klare exemplaren uit. Als er een lezer binnenkomt, wordt er niets gekookt.
Technisch gezien is Hugo een static site generator: één programma, geschreven in Go, dat Markdown-bestanden, templates en afbeeldingen inleest en een map vol HTML, CSS, afbeeldingen en feeds wegschrijft. Die map is de website. Elke webserver kan hem uitleveren; hier is dat gewoon nginx.
Eén binary, twee edities
Hugo is één uitvoerbaar bestand zonder afhankelijkheden – geen PHP, geen database, geen Node.js. Het komt in een standaard- en een extended-editie; de extended-editie voegt WebP-codering en Sass toe. Deze blog gebruikt de extended-editie, versie 0.169.0, omdat elke afbeelding tijdens de build wordt verkleind en naar WebP omgezet.
De les: Hugo verplaatst al het werk van het moment van het bezoek naar het moment van publiceren. Al het andere in deze post volgt daaruit.
⚖️ Hugo tegenover WordPress
| Vraag | WordPress | Hugo |
|---|---|---|
| Wanneer wordt een pagina gemaakt? | Bij elke request (of uit een cache) | Eén keer, tijdens de build |
| Wat draait er op de server? | PHP, MariaDB, vaak Redis | Alleen de webserver |
| Aanvalsoppervlak | Login, admin, plugins, XML-RPC, PHP | Statische bestanden |
| Regelmatige updates | Core, plugins, thema’s, PHP | nginx; Hugo alleen op de buildmachine |
| Waar schrijf ik? | Editor in de browser | Teksteditor, Git |
| Reacties, formulieren | Ingebouwd | Externe dienst nodig |
| Snelheid | Gecachet: 58 ms voor de voorpagina | 57 ms – geen verschil |
| Paginagewicht (voorpagina, zonder afbeeldingen) | 25 bestanden, 198 KB | 3 bestanden, 9,5 KB |
De cijfers komen uit mijn eigen metingen van vóór de verhuizing. Snelheid was niet de reden: een goed gecachete WordPress is net zo snel. De redenen waren de rest van de tabel – geen login om aan te vallen, niet elke week plugin-updates, geen database om te back-uppen, en een pagina die 95 % kleiner is.
Wat ik opgaf: de editor in de browser, reacties en het gemak om een functie met één klik te installeren.
De les: WordPress is een programma dat een website produceert. Hugo produceert de website één keer en stapt dan opzij. Of dat beter is, hangt ervan af of je nodig hebt wat alleen het draaiende programma kan.
🔧 Hoe Hugo werkt
Content: Markdown met front matter
Elke post is een Markdown-bestand. Bovenaan staat de front matter, een YAML-blok dat Hugo als data inleest. Een post op deze blog begint zo:
---
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
---
Onder de tweede --- komt de tekst. Markdown dekt koppen, lijsten, tabellen en code; waar dat niet genoeg is, mag ruwe HTML (unsafe = true in de Goldmark-instellingen), wat belangrijk is voor de posts die uit WordPress zijn omgezet.
Mappen, secties en adressen
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 bepaalt de adressen: posts = "/:year/:month/:day/:slug/" houdt het URL-schema aan dat WordPress gebruikte, dus er is geen enkele oude link gebroken. Categorieën en tags zijn taxonomies; Hugo bouwt zelf een pagina voor elke categorie en elke tag.
Templates
De templates gebruiken de templatetaal van Go. baseof.html is het frame van elke pagina, page.html een losse post, home.html de startpagina, en partials zijn herbruikbare stukken – de header, de sidebar, de <head> met alle metatags. Ik gebruik geen kant-en-klaar thema: de layouts zijn geschreven om op het oude WordPress-thema te lijken.
De asset-pipeline
Hugo verwerkt bestanden zelf: resources.Get "css/main.css" | minify | fingerprint minificeert het stylesheet en zet een hash in de bestandsnaam, zodat browsers het voor altijd kunnen cachen. Afbeeldingen worden tijdens de build verkleind – de previewafbeelding voor social media bijvoorbeeld wordt uit de postafbeelding op 1200 px gemaakt en verder verkleind tot hij onder 280 KB blijft, de grens voor WhatsApp-previews.
Meertalig vanaf het begin
Elke taal heeft in hugo.toml een eigen contentmap, label en locale. Posts die bij elkaar horen delen een translationKey; daaruit weet Hugo de vertalingen van elke pagina en bouwt het de taalkeuze en de hreflang-links. Deze blog heeft nu acht talen – Engels, Duits, Frans, Spaans, Italiaans, Portugees, Nederlands en Pools.
Preview en concepten
hugo server bouwt de site in het geheugen en serveert hem op localhost:1313; elk opgeslagen bestand herlaadt de browser. draft: true houdt een post buiten de echte build, en een datum in de toekomst doet dat ook – daarover hieronder meer.
De les: content, templates en configuratie zijn drie aparte soorten bestanden. Je kunt het uiterlijk veranderen zonder één post aan te raken, en een post schrijven zonder te weten hoe de templates werken.
🧩 Waar de plugins gebleven zijn
Bij WordPress was bijna elke functie een plugin. Bij Hugo is een functie ofwel ingebouwd, ofwel een paar regels template, ofwel een klein script dat na de build draait.
| WordPress-plugin | Taak | Nu |
|---|---|---|
| Yoast SEO | Titel, description, canonical, Open Graph, gestructureerde data | head.html (één template voor alle pagina’s) |
| Yoast SEO | Sitemap | Ingebouwd in Hugo, eigen sitemap.xml-template met hreflang |
| Yoast SEO | “Je post heeft geen description” | check_posts.py: de build stopt |
| Polylang | Talen, taalkeuze | Ingebouwd in Hugo |
| CompressX | WebP-afbeeldingen, kleinere formaten | Beeldverwerking van Hugo |
| Autoptimize | CSS, JS, HTML minificeren | hugo --minify |
| WP Super Cache, Redis | Pagina- en objectcache | Niet nodig – elke pagina is al een bestand |
| Zoeken (WordPress) | Full-text zoeken | Pagefind (volgende sectie) |
SEO zonder plugin
Yoast deed drie dingen: het schreef metatags, het bouwde een sitemap en het zeurde. De eerste twee zijn nu één partial, head.html. Voor elke pagina schrijft het de titel (of een kortere seoTitle uit de front matter), de description, een canonical-link, één hreflang-link per vertaling, de Open Graph- en Twitter-tags met een gegenereerde previewafbeelding, de artikeldata en een JSON-LD-blok met dezelfde gestructureerde data die Yoast maakte (Article, WebPage, BreadcrumbList, Person). Het is één bestand, en het is voor elke pagina hetzelfde – geen instellingenscherm per post.
Het zeuren is naar de build verhuisd: tools/check_posts.py stopt de build als een post geen titel, description, afbeelding, afbeeldingstekst, vertaalsleutel of datum heeft, of als het afbeeldingsbestand niet bestaat, en het waarschuwt als een description te lang wordt of een vertaling ontbreekt.
Uitbreidingen in Hugo
Hugo heeft geen pluginwinkel, maar wel uitbreidingspunten:
- Thema’s en Hugo Modules – complete looks of stukken ervan, binnengehaald als een dependency. Deze blog mount zijn eigen mappen via
module.mounts(de uploadmap wordt twee keer gemount: één keer voor de beeldverwerking, één keer als/wp-content/uploads/zodat de oude afbeeldingsadressen blijven werken). - Shortcodes – kleine templates die je vanuit Markdown aanroept, bijvoorbeeld voor een video of een meldingskader.
- Render hooks – je eigen template voor elke link, afbeelding of kop die Markdown oplevert.
- Outputformaten – dezelfde content als HTML, RSS, JSON of wat dan ook.
- Tools na de build – de build is gewoon een map, dus elk programma kan ermee aan de slag. Hier voegt
imgattrs.pysrcseten lazy loading toe aan de afbeeldingen in oude posts, en bouwt Pagefind de zoekindex.
De les: de meeste plugins losten problemen op die een statische site niet heeft. De rest werd een template of een script dat ik helemaal kan lezen – wat ook betekent dat niemand anders ze voor mij bijwerkt.
🔍 Hoe zoeken werkt zonder server
Een zoekveld lijkt een server nodig te hebben: iemand moet de woorden toch opzoeken. Pagefind verplaatst ook dat werk naar de build.
- Tijdens de build leest Pagefind elke kant-en-klare HTML-pagina. Het indexeert alleen het deel dat met
data-pagefind-bodyis gemarkeerd (het artikel), zodat menu’s en sidebars de resultaten niet vervuilen, en slaat alles over wat metdata-pagefind-ignoreis gemarkeerd. Het herkent de taal aan hetlang-attribuut en bouwt één index per taal. - De index is opgesplitst in veel kleine bestanden onder
/pagefind/– 18 MB in totaal voor acht talen. Niemand downloadt het allemaal. - In de browser wordt niets geladen totdat iemand echt zoekt. Dan importeren een paar regels JavaScript Pagefind, dat alleen de indexstukken voor de ingetypte woorden en de fragmenten van de gevonden pagina’s ophaalt, en titel en uittreksel toont.
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(); })); })
Een bijeffect dat ik prettig vind: de zoekterm bereikt de server nooit als query string, dus hij belandt niet in een accesslog. Het formulier is met opzet verborgen voor browsers zonder JavaScript – een gewone formulierverzending had de term in de URL gezet.
De les: “statisch” betekent niet “geen interactie”. Het betekent dat de interactie in de browser van de lezer plaatsvindt, met data die vooraf is klaargezet.
✍️ Mijn workflow voor een nieuwe post
- Schrijven: het Markdown-bestand in
site/content/en/posts/<slug>.mdmet de front matter van hierboven. De vertalingen krijgen dezelfde bestandsnaam, dezelfdetranslationKeyen tags met een taalsuffix (hugo-de,hugo-fr, …). - De afbeelding toevoegen in
site/uploads/YYYY/MM/– WebP, maximaal 1536 px breed, onder 280 KB. In de tekst worden afbeeldingen aangeroepen als/wp-content/uploads/YYYY/MM/name.webp, het adres dat WordPress gebruikte. - Builden:
tools/build.sh
Het draait check_posts.py, dan hugo --gc --minify, dan imgattrs.py, dan Pagefind. Hugo zelf heeft zo’n tien seconden nodig voor de hele site.
- Publiceren:
tools/deploy.sh <host> 10022
rsync uploadt de build naar een map incoming/; de server kopieert hem daarna naar een nieuwe releasemap en zet in één stap een symlink om. De laatste vijf releases blijven staan, dus tools/deploy.sh <host> 10022 rollback gaat in een seconde terug. De deploy-key kan verder niets – de server accepteert voor die key alleen precies deze commando’s.
- Committen en pushen van de content-repository.
Twee repositories: open code, privé content
De server en de buildtools staan in een publieke repository, www_hugo, naast de Ansible-code voor al het andere. De content – posts, afbeeldingen, templates, concepten – staat in een privé-repository. De reden is dat een repository alles onthoudt: een afbeelding die ik offline haal, zou voor altijd in de geschiedenis van een publieke repo blijven staan, en concepten zijn niet bedoeld voor lezers. De server krijgt alleen kant-en-klare bestanden via de deploystap en ziet nooit een concept; de publieke repo ziet de inhoud helemaal niet.
De les: publiceren bestaat uit twee onafhankelijke stappen. De server toont wat het laatst gedeployed is, Git bewaart wat het laatst gecommit is – ik doe allebei, in die volgorde.
⬆️ Hugo updaten
Hugo is helemaal niet op de server geïnstalleerd. Het staat als één binary in .tools/ op de machine die de site bouwt, samen met Pagefind. De versies zijn vastgepind in versions.yml van de publieke repo:
hugo_version: "0.169.0" # github.com/gohugoio/hugo/releases
pagefind_version: "1.6.0" # github.com/Pagefind/pagefind/releases
Een update volgt hetzelfde patroon als al het andere hier:
- De release notes lezen – Hugo markeert af en toe templatefuncties als deprecated en waarschuwt daar in de build-output al lang voor het ze verwijdert.
- De extended-release voor Linux downloaden, de SHA-256 vergelijken met het checksumbestand van de release,
.tools/hugovervangen. - In een aparte map builden en die vergelijken met de vorige build (
diff -r). Er mogen alleen verwachte verschillen opduiken. - De pin in
versions.ymlaanpassen, deployen, committen.
Omdat de server alleen bestanden serveert, kan een Hugo-update de draaiende site nooit stukmaken. Het ergste geval is een build die mislukt of er anders uitziet – en dat gebeurt op mijn machine, niet voor de ogen van lezers.
De les: de generator is een buildtool, net als een compiler. Pin hem vast, update hem bewust en vergelijk de output.
🤖 Wat Claude rond Hugo doet
Het meeste werk aan deze blog doe ik samen met Claude (de AI van Anthropic) in de terminal. Uitgesplitst per onderwerp:
- Migratie: export uit WordPress, omzetting van elke post naar Markdown met front matter, oude adressen en afbeeldingspaden behouden, redirects voor gewijzigde slugs.
- Templates en uiterlijk: het oude thema nabouwen in Hugo-templates, de slider, de sidebar, de donkere hoekjes zoals de datumarchiefpagina’s.
- SEO: de
head.html-partial, de sitemap methreflang, gestructureerde data, previewafbeeldingen onder de WhatsApp-grens. - Schrijven en vertalen: concepten in mijn woorden, vertalingen in alle acht talen met vaste regels (codeblokken byte-identiek, links per taal herschreven) en een checker die elke vertaling met het Engelse origineel vergelijkt.
- Controles: de buildcontrole, een linkcontrole over alle gegenereerde pagina’s, een live controle tegen de draaiende site.
- Server en deploy: de Ansible-role voor nginx, de atomaire deploy, SELinux, monitoring.
- Troubleshooting: uitzoeken waarom een post niet verscheen (zie de volgende sectie) of waarom een breadcrumb naar een ontbrekende pagina wees.
Wat bij mij blijft: beslissen wat er geschreven en gepubliceerd wordt, elk concept lezen, de playbooks draaien, en elke push en deploy – Claude vraagt het voor elk ervan.
De les: een statische site bestaat uit tekstbestanden en kleine scripts – precies het materiaal waar een AI-assistent goed mee overweg kan. De beslissingen blijven van mij.
🐛 Valkuilen die pas in de praktijk opdoken
- Een post uit de toekomst wordt niet gebouwd. Ik zette de datum van een post op 15:50 en buildde om 15:44 – Hugo liet hem stilletjes weg. Geen fout, de post ontbrak gewoon.
datemoet in het verleden liggen, of de build heeft--buildFuturenodig. - Een ontbrekende dagpagina. De breadcrumb van een nieuwe post linkte naar zijn dagarchief (
/2026/11/13/), dat niet bestond omdat de datumpagina’s contentbestanden zijn en geen gegenereerde pagina’s. De linkcontrole vond het; nu heeft een nieuwe datum zijn eigen_index.mdnodig. En terwijl ik juist deze post schreef, gebeurden beide fouten opnieuw: de post was gedateerd op 08:30 en gebouwd om 08:22, en zijn nieuwe dagpagina had 12:00 – een pagina die om twaalf uur ’s middags is gedateerd, ligt de hele ochtend in de toekomst. - Omgezette HTML is kwetsbaar. Posts die uit WordPress zijn geïmporteerd, zijn een mix van Markdown en ruwe HTML. In een paar ervan waren woorden aan elkaar geplakt of had een verdwaalde
**het overleefd. Alleen een controle van de gerenderde pagina’s in alle talen vond ze. - Typografie-instellingen doen ertoe. De typographer van Hugo maakt standaard van
--een streepje. WordPress deed dat niet, dus commando’s als--checkzouden in oude posts–checkzijn geworden. De instelling raakt nu alleen nog aanhalingstekens en apostrofs. - Niet alles hoort in de zoekfunctie en de feeds. Het colofon en de privacyverklaring bevatten het postadres. Ze zijn
noindex, blijven buiten de RSS-feeds en buiten de Pagefind-index – een plugin had voor elk daarvan een instelling nodig gehad, hier is het een voorwaarde in de templates. - Sommige adressen komen uit de front matter. Een paar oude posts hebben een
url:-sleutel met het volledige pad. In vertalingen heeft die het taalvoorvoegsel nodig, anders claimen alle talen hetzelfde adres.
De les: Hugo doet precies wat je zegt en klaagt zelden. De controles die WordPress-plugins stilletjes deden, moet je opschrijven – en dan draaien ze bij elke build.
📊 Gemeten
| Posts | 146, in 8 talen |
| Gegenereerde HTML-pagina’s | ongeveer 23.000 (posts, tags, categorieën, archieven) |
| Hugo-build | ongeveer 10 s (hele site) |
| Outputmap | 498 MB, bijna allemaal afbeeldingen |
| Zoekindex | 18 MB voor 8 talen, in kleine stukjes geladen |
| Software op de server voor de blog | nginx |
🎯 De lessen
- Bepaal waar het werk gebeurt: bij het bezoek (WordPress) of bij het publiceren (Hugo).
- Controleer wat een plugin echt deed voordat je hem vervangt – het meeste is één template, een deel is een controle die je zelf moet schrijven.
- Zoeken, feeds en sitemaps werken zonder server als de build de data klaarzet.
- Pin de generator vast zoals elke andere buildtool en vergelijk de output vóór het deployen.
- Een ontbrekende post zonder foutmelding heeft meestal een datum in de toekomst.
- Houd content en code gescheiden als de code openbaar is.
