Hugo

Lightweight static site utility



Assumed audience:

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

the eponymous Hugo

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

I mostly use it at 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

Minuses:

  1. documentation confusing and abstruse
  2. mathematics support is a dumpster fire
  3. when hugo is used as a backend to other things (quarto, blogdown) it is only the stock/default hugo which does not include the powerful plugins or community support.

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. it is ginding 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. (This seems to be

  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:

via quarto

See quarto.

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

Caddy

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


No comments yet. Why not leave one?

GitHub-flavored Markdown & a sane subset of HTML is supported.