Hugo

Having used Hugo for a some years now, while creating a few dozen entries, I have discovered a few “best practices” for organizing the raw (Markdown) content.

This site is generated using Hugo. Getting the site up and running was nothing short of a nightmare, which I have documented elsewhere. But things are working now, and Hugo makes adding new content very easy indeed. It therefore seems a good opportunity to reflect back and revisit the whole “Static Site Generator” a.k.a. “JamStack” topic, from a greater distance.

I just wasted one hour and five minutes, dealing with two of these opaque, unexpected, and almost undiagnosable showstopper roadblocks that Hugo will throw your way - much too often, in my opinion.

Hugo is a static site generator: it takes some plain-text content, marries it to a bunch of HTML templates, and produces a set of complete, static HTML pages that can be served by any generic, stand-alone web server. Simple.

I have compiled my various write-ups on the Hugo site generator into a single, consecutive guide.

I came across an unexpected problem when using Mathjax in a Markdown document (to be used with the Hugo site generator).

Getting Hugo to work with Mathjax (or vice versa) to create these pages took a little bit of fiddling and some trial-and-error.

Having managed to produce this site using the Hugo static site generator, it’s time to reflect and collect my impressions.

The Hugo static site generator takes some plain-text content, marries it to a bunch of HTML templates, and produces a set of complete, static HTML pages that can be served by any generic, stand-alone web server. It selects templates based on the type of the content, and its position in the filesystem.

The Hugo static site generator takes some plain-text content, marries it to a bunch of HTML templates, and produces a set of complete, static HTML pages that can be served by any generic, stand-alone web server. Because the site generated by Hugo is entirely static, all URLs in the public site must correspond directly to objects in the filesystem.