Jeff Avery ▮

Static Site Generators

I wrote back in 2021 about using Hugo to generate my course website. Since then, I’ve experimented with different ways of generating course websites. It’s time to revisit the details on what I’ve attempted, and where I’ve landed.

Overview

A Static Site Generator is just a program that transpiles content (and associated media) from a human-readable format into a web-publishable format e.g., Markdown to HTML/CSS/JS. There are SSGs that are meant to run on a hosted platform e.g., GitBook, but I tend to restrict myself to those that generate standalone sites. They’re easier to deploy, and they keep my IP on University servers where I have control.

Features

Required

  • Generates a standalone site from Markdown files and assets.
  • Display inline images at different resolutions i.e. supports image scaling.
  • Embed video files e.g., previews of YouTube videos with links through to the actual recording.
  • Show annotations i.e. blocks of text for Alerts, Warnings and so on.
  • Code blocks with syntax highlighting e.g., Kotlin, SQL and shell scripts.
  • Useful navigation including expandable Table of Contents, ability to search the site.
  • Scales up to 100 pages without major performance issues.

Nice-to-have

  • Plugins to extend functionality further.
  • Ability to tweak CSS e.g., adjust table borders.
  • Hide pages that are draft/in-progress.
  • Ability to host private content w. login.

Comparison

Over the past few years, I’ve tried different SSGs. Each one of these meets the basic criteria above. The basic experience is similar:

  1. Generate a skeleton website. Configure a YAML or TOML file to enable features, and so on.
  2. Copy/paste course notes (markdown files and images) into the fixed directory structure for the site.
  3. Reformat pages if needed to match the style of Markdown supported. Often features like table formatting and image resizing are not standard, so you often need specialized syntax based on the system you’re using.
  4. Find and install plugins for more esoteric functionality. e.g., hiding pages.
  5. Test. Test again. Fix content that doesn’t display properly.

Yes this is a considerable amount of work to get running, but once it’s available, edits are relatively simple.

What are my experiences with each site generator - pros and cons of each?

Hugo

Download from Hugo.

The OG. Hugo is an Open Source static site generator built in Ruby. It’s the most popular one, with lots of support, including different themes to try. I originally started in 2021 with Hugo and the Relearn documentation theme.

Pros

  • All features are met.
  • Tons of themes to choose from.
  • Very stable.

Cons

  • Slow to build. Slow navigation and loading.
  • Features are mostly implemented in themes. i.e. image resizing might exist in one theme and not another. Syntax will also differ which locks you into a theme. Effectively, how your installation will look and behave is based completely on the theme. This is great if you have a theme that you love, but if not…
Theme Where it’s great What it’s missing
Relearn It has every feature. Active project. UI isn’t great
Hextra Fantastic UI/UX! Fixed structure (landing page). No image resizing (but can handle with HTML).
Doks Great feature support. Fixed structure (landing page, docs, blog).

It’s hard to not love Hugo. You’re reading this on a Hugo site, with the Maverick theme!

Jekyll

Download from Jekyll.

Pros

  • Very capable, all base functionality.
  • For a time, was more popular than Hugo. This trend has reversed recently.

Cons

  • Same reliance on themes as Hugo, but fewer themes available.
  • Jekyll requires a Ruby environment and Ruby installations can break. Mine stopped working one day, and after a couple of hours of trying to patch it unsuccessfully, I switched to a different engine.

Retype

Download from Retype.

Pros

  • Very polished, sold as a commercial product with a free limited license.
  • Great up to 100 pages (then you have to pay).

Cons

  • Limited ability to tweak the functionality.
  • No themes, so you cannot change the look and feel.
  • Side-bar TOC is fixed and cannot be removed.
  • Scaling issues on small screens.

mdbook

Download from mdbook.

Pros

  • Used by rust documentation project, so stable.
  • Can adjust CSS e.g., table formatting can be tweaked.
  • Fast!

Cons

  • Only really used by rust documentation project, not as popular as others.
  • Fewer features.

This is what I used for CS 346 W25. I liked the simplicity, and it let me tweak the CSS to improve readability of pages that felt “cramped” under Retype e.g., course schedule table.

Current Recommendation

There is no perfect solution, but I’ve settled back into using Hugo with specific themes:

As much as I like some of the other solutions, Hugo is simply better-supported. I used mdbook for a term and really liked it, but there’s not a lot of active development going on. Hugo with a newer theme is the easiest way to get QoL features like search, light/dark themes, and mermaid support for diagrams.

#markdown

July 20, 2025 ∙