Jeff Avery ▮

Generating Course Websites

I wrote back in 2021 about using Hugo to generate my course website. Since then, I’ve used an SSG to generate course websites every term for all of the courses that I teach. It’s time to revisit the details on what I’m doing currently.

Overview

A Static Site Generator is just a program that transpiles content (and associated media) from a human-readable format into a more 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 complete 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 (usually 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 in-progress.
  • Login for specific pages.

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 some configuration scripts 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 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. 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 used to use 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…

Note that I still love Hugo. You’re reading this on a Hugo site, with a different 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.

mdbook

Download from mdbook.

Pros

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

Cons

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

This is what I’m currently using 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.

#markdown

March 24, 2025 ∙