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.

Een kleine robot op een lopende band maakt van Markdown-pagina's kant-en-klare HTML-pagina's en plakt er SEO-labels op, de monitor toont Markdown → Hugo → HTML

🌐 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

VraagWordPressHugo
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 RedisAlleen de webserver
AanvalsoppervlakLogin, admin, plugins, XML-RPC, PHPStatische bestanden
Regelmatige updatesCore, plugins, thema’s, PHPnginx; Hugo alleen op de buildmachine
Waar schrijf ik?Editor in de browserTeksteditor, Git
Reacties, formulierenIngebouwdExterne dienst nodig
SnelheidGecachet: 58 ms voor de voorpagina57 ms – geen verschil
Paginagewicht (voorpagina, zonder afbeeldingen)25 bestanden, 198 KB3 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-pluginTaakNu
Yoast SEOTitel, description, canonical, Open Graph, gestructureerde datahead.html (één template voor alle pagina’s)
Yoast SEOSitemapIngebouwd in Hugo, eigen sitemap.xml-template met hreflang
Yoast SEO“Je post heeft geen description”check_posts.py: de build stopt
PolylangTalen, taalkeuzeIngebouwd in Hugo
CompressXWebP-afbeeldingen, kleinere formatenBeeldverwerking van Hugo
AutoptimizeCSS, JS, HTML minificerenhugo --minify
WP Super Cache, RedisPagina- en objectcacheNiet nodig – elke pagina is al een bestand
Zoeken (WordPress)Full-text zoekenPagefind (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.py srcset en 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.

  1. Tijdens de build leest Pagefind elke kant-en-klare HTML-pagina. Het indexeert alleen het deel dat met data-pagefind-body is gemarkeerd (het artikel), zodat menu’s en sidebars de resultaten niet vervuilen, en slaat alles over wat met data-pagefind-ignore is gemarkeerd. Het herkent de taal aan het lang-attribuut en bouwt één index per taal.
  2. De index is opgesplitst in veel kleine bestanden onder /pagefind/ – 18 MB in totaal voor acht talen. Niemand downloadt het allemaal.
  3. 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

  1. Schrijven: het Markdown-bestand in site/content/en/posts/<slug>.md met de front matter van hierboven. De vertalingen krijgen dezelfde bestandsnaam, dezelfde translationKey en tags met een taalsuffix (hugo-de, hugo-fr, …).
  2. 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.
  3. 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.

  1. 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.

  1. 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:

  1. 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.
  2. De extended-release voor Linux downloaden, de SHA-256 vergelijken met het checksumbestand van de release, .tools/hugo vervangen.
  3. In een aparte map builden en die vergelijken met de vorige build (diff -r). Er mogen alleen verwachte verschillen opduiken.
  4. De pin in versions.yml aanpassen, 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 met hreflang, 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

  1. 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. date moet in het verleden liggen, of de build heeft --buildFuture nodig.
  2. 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.md nodig. 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.
  3. 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.
  4. Typografie-instellingen doen ertoe. De typographer van Hugo maakt standaard van -- een streepje. WordPress deed dat niet, dus commando’s als --check zouden in oude posts –check zijn geworden. De instelling raakt nu alleen nog aanhalingstekens en apostrofs.
  5. 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.
  6. 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

Posts146, in 8 talen
Gegenereerde HTML-pagina’songeveer 23.000 (posts, tags, categorieën, archieven)
Hugo-buildongeveer 10 s (hele site)
Outputmap498 MB, bijna allemaal afbeeldingen
Zoekindex18 MB voor 8 talen, in kleine stukjes geladen
Software op de server voor de blognginx

🎯 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.
Sommige teksten en afbeeldingen op deze site zijn met hulp van AI gemaakt of door AI gegenereerd. Details