How this site is built and published

Meta-content time!

As the site develops, this post will be updated.

Static blog engine: Hugo

The excellent Hugo is used to build this site.

Now that I’ve configured and tweaked Hugo it mostly stays out of the way. I can quickly preview and iterate what I’m doing in a local browser (and the automatic reloading is doubleplusgood).

Hosting

This site is hosted from a worker in a free-tier Cloudflare account. The worker does a Hugo build and deploy on any changes to the github repo for this site; I just have to push to github to update the site (and the update to the live site is < 1min usually).

Cloudflare obviously want to up-sell you to a paid account, so the free tier has various things nerfed, e.g. any embedded video player is stripped out.

The free-tier Cloudflare account does make some analytics available to you.

Analytics

For anonymous visitor stats I’m using Plausible.io , self-hosted in a Digital Ocean droplet.¹ I highly recommend Plausible, I love their anonymity-first mission (and I encourage you to periodically donate to the project if you self-host). Check out this comparison of Plausible to Cloudflare’s analytics .

I wanted to avoid Google Analytics for privacy reasons (and it’s bloated, to boot).

I’ve integrated Plausible into Hugo by using the Community plugin (which Plausible themselves recommend as the best way).

Removing your own live site visits from Plausible stats

If you don’t have lots of traffic, this is worth doing.

There’s a few ways to achieve it. I’m using the local storage method which is pretty convenient.

Avoiding Ad-blockers skewing your stats

Some users’ ad-blockers stop the Plausible script from loading, which means no analytics are reported.

If you’d like to get around that, have a look at the proxy method that Plausible recommend.

I’ve not implemented this myself yet, but I’m considering it. Personally I’m OK with defeating an ad-blocker if it’s for privacy-first analytics like Plausible.

Command line tooling

I’m using Just to build and locally serve Hugo content. It’s like make without the tentacles and horror.²

Punctuation conversion in markdown

Hugo sometimes does automatic conversion of e.g. upright apostrophes ' into pairs like ‘this’, but in some cases I’ve had to manually use left and right apostrophes. I probably need to tweak the config more.³

In the same vein, if I type ‘--’ (two hyphens) then I end up with an em-dash ‘–’, which is what I want.⁴ Plausible sometimes-but-not-always converts space-hyphen-space into em-dash.

Maths content

I’m using the MathsJax plugin to typeset equations.

It turns this:

$$
f(a, b) = \textrm{rot}_\psi(a, 30) + \textrm{rot}_\theta(b, 30)
$$

into this:

which is remarkable, especially to a simple-minded farmhand from Tatooine like me.

Offline mathjax rendering

If you import mathsjax from a CDN link you’ll find offline blog editing breaks the maths rendering.

As a workaround, download a local copy of a mathjax release for rendering and load that if running locally.

Here’s my maths.html partial:

{{ if eq hugo.Environment "development" }}
  <!-- Local MathJax 3.2.2 for offline dev (will work offline) -->
  <script id="MathJax-script" async src="{{ .Site.BaseURL }}mathjax/es5/tex-chtml.js"></script>
{{ else }}
  <!-- CDN MathJax for Production -->
  <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
{{ end }}

<script>
  MathJax = {
    tex: {
      displayMath: [['\\[', '\\]'], ['$$', '$$']],  // block
      inlineMath: [['\\(', '\\)']]                  // inline
    }
  };
</script>

Abecedarium

It’s handy for a writing site to have an Abecedarium for quick checking of rendering, and as a place to record any house-style reminders. Here’s mine.

• Writing