Building Websites with Hugo & Markdown

In a previous post, I talked about the value in using Markdown to generate course notes. I’ve continued to refine my use of Markdown, and I’m convinced that it’s still the fastest way to generate semi-structured content for my courses1

I’ve also recently started using Hugo to generate websites. Hugo is a static site generator that takes Markdown source files and related assets, and generates a static website from your content. It supports many, many different themes, so you can pick something that works for particular style of content.

Using Hugo in CS 349

I’ve recently moved the CS 349 website to Hugo, and I’m amazed at how functional the site is compared to the older manually-generated site.

Here’s a screenshot of my course home page. There are a large number of elements that aid in navigation, from the generated table-of-contents, to search capabilties and tags across related pages.


Content is also well-formatted. Images are captioned and scaled properly and even source code is highlighted properly based on the target language. The syntax highlighting of the Kotlin code was generated by Hugo; all I had to do in the Markdown source was tag the language for this block.


Creating a Website

The main Hugo website is here:

  1. Download and install the Hugo binaries. e.g. to install from Homebrew for Mac).

    $ brew install hugo

  2. Use the Quickstart guide to get a basic website up-and-running.

  3. Optionally, find a new theme from the Hugo Themes site. I use the Learn theme for my course websites. The theme determines a lot of your capabilities e.g. table-of-contents and navigation.

  4. Create content.

  5. Run hugo to generate your site, and upload it. That’s it!

Site Structure

Once you’ve walked through the setup, you should have a directory structure like this:

├── archetypes/
├── config.toml
├── content/
├── data/
├── layouts/
├── public/
├── resources/
├── static/
└── themes/

Suggestions generates the website

#!/usr/bin/env bash
rm -rf public/*
hugo -D deploys it to my local machine for testing

#!/usr/bin/env bash
open -a http://localhost:1313/~cs398/
hugo server -D uploads to the appropriate location

#!/usr/bin/env bash
rsync -var ./public/ --delete


My workflow for editing pages is to

  1. No it’s not nearly as precise as LaTeX, but it’s precise-enough, and much faster to publish to the web. ↩︎