Hugo

Lightweight static site utility which is as fast and elegant as it is stubborn

August 26, 2020 — January 13, 2024

academe
faster pussycat
how do science
plain text
workflow

Assumed audience:

Casual static site users who don’t have time to internalize the nerdview Hugo manual

Figure 1: the eponymous Hugo

hugo is a static site generator which I happen to find amenable sometimes. Its documentation is confusing and abstruse.

I mostly use it as a backend for blogdown, but it is useful for other sites.

Pluses:

  1. fast (build times are quick)
  2. compact (does not install hundreds of megabytes of crap when you run it like most node.js-based ones)
  3. sort of easy, in that I do not need to learn to write javascript components to do basic stuff
  4. powerful shortcodes to do formatting stunts
  5. deep integration of markdown processing
  6. many community plugins
  7. minimalist and simple design

Minuses:

  1. documentation confusing and abstruse, as mentioned
  2. mathematics support is a dumpster fire
  3. when hugo is used as a backend to other things (quarto, blogdown) we have access to only the stock/default hugo, which does not include the powerful plugins.
  4. the design is so simple and minimalist that simple features and yet powerful like passing command-line options to sub programs, which add little complexity and add a lot of power, get bogged down for years despite massive community support and many attempts to implement them

1 Hugo sucks at mathematics

For 4 years or so there has been an argument about hugo and math support. The current settlement is that it can work natively but that is tedious, and there are extensions that make it not terrible (goldmark-mathjax) but they are not where you need them (e.g. not supported by standard hosts) i.e. using mathematics in hugo is grinding low-level friction and irritating hacks. In Add MathJax build support – post-hugo processing · Issue #6694 · gohugoio/hugo, shreevatsa summarises:

(at least) two issues are mixed up here:

  1. Input syntax: MathJax (LaTeX) syntax versus Markdown. The question of whether a user can just type LaTeX syntax, or needs to incorporate many workarounds like escaping underscores and backslashes, so that after passed through Markdown the intended LaTeX syntax remains. […]

  2. Server-side versus client-side processing: Whether the HTML ultimately generated by Hugo should simply contain the MathJax input (to be processed by client-side—i.e. JavaScript—MathJax in the reader’s browser) or should already be processed (server-side) via MathJax (so no JavaScript needs to run client-side).

If a user is happy with special input and client-side MathJax, then this is already possible with stock Hugo by

  1. being super-careful about escaping all Markdown-special characters in one’s input (probably not practical), or using shortcodes / .inner, and

  2. loading the MathJax (or KaTeX) JavaScript in the header or body of one’s page.

But otherwise, either problem is unsolved AFAICT.

Various arguments about how to fix it:

Workarounds to shoehorn the current configuration into working:

Forks of hugo supporting better fixes:

2 Hugo citations

Natively I have no idea. Citations are supported via pandoc, however the hugo configuration options using the pandoc rendered are insufficiently flexible. A secret pro tip is that hugo already supports pandoc config via double metadata YAML blocks. However it does not support configuring the necessary command-line flags.

3 via quarto

See quarto.

4 frontends

4.1 site.js

Site.js is one of several neat tools that integrates hugo.

One person.

Develop and test on your own device. One server.

Sync and deploy to your own VPS. One site.

Host your own site at your own domain

4.2 Skeletron

Skeletron

The Hugo static site generator, a blog aware markdown editor and a dead simple Git client all into one beautiful Mac app.

4.3 Caddy

Caddy, is a low-key single serve web server with automatic hugo integration.

5 Events calendar

Native calendar event output is supported but looks a little messy.

Perhaps ingesting content from a remote calendar server is a better idea?

6 Remote content