After almost 30 years of minimal updates, I decided it was time to overhaul this web site with a new tech stack. Since the 90s I'd gotten by with a web server and hand-written HTML files. But there are better ways to create and serve web sites nowadays.

I've been writing Markdown for years and I like it a lot. It's simple, it's much easier to write and maintain than HTML, and there's great tooling for it. Markdown also happens to be the most common format for authoring site content for static site generators.

A static site generator is a tool that takes a collection of content (like Markdown and image files) as input and creates a collection of HTML/CSS/JS/image files as output. It creates a static web site. The site is simple to host and doesn't require any backend, database, language, or framework running on a web server somewhere. You can still use those things if you want to, but you don't need to.

Actually, you don't even need a web server to host a static web site. There are plenty of services like GitHub Pages, Cloudflare Pages, AWS CloudFront, and many more that will host your site's files, for free in most cases. Each service has its tradeoffs, but overall there are some compelling alternatives to operating a traditional web server.

Which SSG?

There's no shortage of static site generators out there. I started with Zola. It seemed fast, had a theme that looked fairly nice, and was relatively simple and easy to get started with. Unfortunately I soon encountered a number of bugs and limitations in both Zola itself and the theme I was using that motivated me to look for something else. I chose Hugo as it seemed similar in some important ways to Zola, but has been around for much longer and has a much larger ecosystem.

I quickly got off to a much better start with Hugo. It's more complicated with many more settings and capabilities, but it's been reliable and many features work well out of the box with little or no effort. Some customizations still require overriding theme templates, but maybe not quite as much as with Zola.

Pros and cons

This new approach gives a number of advantages over the old way:

  • I can author the site with Markdown
  • I can store the site content in a Git repo
  • I can automatically transform images and include galleries in pages
  • I can include other rich content like code blocks and diagrams
  • I can organize the site into sections with auto-generated navigation
  • I can have categories and tags
  • I can use a theme to mostly avoid manual CSS and JS work
  • I can automate building and deployment of the site
  • I can serve the site without a web server

Some disadvantages include:

  • there's a learning curve
  • some components are dated and hindered by questionable philosophical issues
  • some customizations are difficult
  • some customizations require overriding theme templates
  • some customizations require the horrors of CSS
  • there will be breaking changes to Hugo and the theme that will take time to deal with
  • the hugo serve command is not as reliable as a real web server

Tools

  • Hugo, for generating the site from Markdown files
    • PaperMod theme
    • hugo-shortcode-gallery, for image galleries (would like something more modern though)
  • VS Code, for editing Markdown files
  • Prettier extension for VS Code, for wrapping Markdown paragraphs
  • rclone, for deployment

Conclusion

Time will tell how this works out. So far it seems like a major improvement. The barriers to updating and scaling the site feel much lower. The lessons learned could also be applied to other sites and documentation in the future.