Static site generators promise simplicity: write markdown, build, publish.
Reality: you’ll eventually push a broken build at midnight and wonder why nothing works.
Hugo is fast and clean. But self-hosting it means thinking past the happy path.
Automate the Build, Don’t Blindly Trust It
hugo can fail silently if:
- A template breaks
- A missing asset kills the pipeline
- A syntax error skips pages
Wrap the build:
- Run
hugo --gc --minifyin CI with fail-fast - Log build output and email yourself on failure
- Test locally before deploy with the same flags
Fast builds mean fast failures if you don’t watch.
Version and Verify
Treat site code like any other:
- Keep it in git; tag releases
- CI pipeline should build artefacts, not live servers
- Verify links with a linter (
html-proofer) to catch silent 404s
Publishing shouldn’t be blind faith.
WebDAV Isn’t Bulletproof
Fastmail’s WebDAV is solid but not infallible:
- Timeouts can leave half-deployed sites
- DNS hiccups mid-sync break uploads
- Conflicting file states confuse clients
Mitigate with:
- Atomic deploys (upload to a temp dir, swap symlink)
- Use checksums to confirm upload integrity
- Roll back to previous release on failure
Caching and CDN Edge Cases
Static doesn’t mean instant:
- Browser/CDN caches can serve stale pages
- Force cache busting with versioned asset paths
- Purge caches on deploy when possible
Users don’t care if your build is fixed if they still see the old bug.
Boring Failsafes
Build a boring fallback:
- Keep the last known-good build locally and remotely
- Automate a rollback command in case of deploy disaster
- Document the whole process for future you
Static sites are “set and forget” until they aren’t.
A little paranoia saves midnight panics.