I’m not fond of the word “blog”. I don’t know why but it just gives me an ick. But there isn’t a better way to describe what you’re reading right now. It’s a blog. My new blog. Thanks for dropping by.

I find the barrier to entry is the most important thing if I’m going to get any wriing done. Given that I work in software, you might expect that I would enjoy fiddling with some homespun frankenblog that is broken more often than not. But you would be wrong – unnecessary complexity in software, and the wasted time that goes with it, makes me want to play in traffic.

Writing is something I enjoy once I sit down, but I baulk and procrastinate whenever there are bumps or points of friction in editing, publishing, and sharing what I’ve written.

I’m not an experienced technical writer, but we’re all starting from somewhere. I thought I could share some of my experiences which informed how I designed this new blog, which uses Hugo, to try and make writing simple.

Past instances of writing things

An early piece of technical writing I did was to write a 6-part series of instructional tutorials for game programming in Java using LibGDX for workshops at university. Stepping tactfully over whether these tutorials were any good, the process of writing them was a disaster. They were painstakingly written in .docx documents (callouts, code snippets, and all), exported into .pdf, and distributed by email or shared network drive.

Terrible experience, 2/10, would only try again with the boundless energy of youth.

Manual code snippets in Word, never again

As part of my studies I produced an honours thesis on deep reinforcement learning. In the sciences LaTeX is a common standard for publication typesetting. I wrote my thesis using ShareLaTeX (now Overleaf), an online platform. This simplified getting started, sidestepping a number of wooly considerations in setting up a LaTeX desktop editor, but tied me to being online whenever I was writing. No online platform could save me, however, from the experience of writing LaTeX itself (shudder).

Yep, still strikes fear into the heart years later

Some time later, I wrote some articles (or, blogged, if we must call it that) on Medium. I don’t know why, given at the time I was learning and using a lot of Ansible. Better to forget.

Medium was a successful platform because it combined a robust and elegant Markdown-ish writing experience, a great reading experience, reader comments, and excellent SEO. At the time, it was also a primarily free platform. Unfortunately, these things often have to come to an end on the modern web and a rising tide of “members only” content and monetisation pushed me away from the platform.

Impressive, I know

Following my experiences with Medium, I explored getting away from any particular online platform by bootstrapping a static site built with Hexo. That effort doesn’t really belong in this post, however, because I never wrote anything on it.

RIP

Choosing Hugo for writing things down

In coming back to writing, I wanted to continue exploring what I started with Hexo: something simple, that I could host myself, and powered by simple Markdown content. I had the following requirements:

  • Static site
  • Markdown content
  • Just host it myself, no platforms
  • Render good-looking code for technical write-ups
  • Easy to theme and customise
  • Don’t be shit at SEO
  • Don’t be shit or a pain in the neck in other ways (seriously, I will put you in the bin)

Here is what I considered and tried:

Hexo

Hexo is a mature Node.js option for generating a static site from Markdown. It does what it says on the tin and doesn’t get in its own way. But I’ve been intentionally trying to branch out of the Node.js ecosystem and I didn’t remember being especially impressed with the experience of using it last time so I gave this one a miss.

Docsify

Docsify is actually as magical as it sounds. Create an index.html, upload it along with some .md files, and it just works. I’ve used it in the past to great success creating a mini-Wiki thing of notes and characters for a tabletop roleplaying group.

The issue with docsify is that, given the content is generated dynamically, the SEO is essentially non-existent. Less than ideal for a blog.

Jekyll

Jekyll is a popular choice and a bit of an OG, but it’s Ruby. Moving along.

Gatsby

Gatsby is a framework for building websites with React. Gatsby felt a bit deep and feature-rich for what I was looking for.

VitePress (and VuePress)

VitePress is a Vue-based static site generator. It is aimed at creating technical documentation which means out of the box it renders really nicely content from Markdown. VitePress is a successor (sort of?) to VuePress, but more streamlined and less flexible.

I have used Vite previously as a replacement for create-react-app tooling and had good results so I did give this one a shot. I did bootstrap something but found it difficult to customise the theme: VitePress doesn’t yet have a concept of plugins or a strong ecosystem, and I found myself needing to pick up more Vue than I was looking for.

Hugo

I settled on Hugo, a popular Go option for generating static sites. The theming and customisation was super straightforward, and I have been intending to learn more Go. ✨

Building with Hugo

When I was looking at Gatsby as an option I came across the blog starter. Something about the minimal, single width, basic bitch nature of it spoke to me. I liked the “about the author” header that became a footer on content pages.

As a starting point for a Hugo theme I settled on Hugo PaperMod and applied some customisation to bring it into a single width layout and introduce the “about the author” ego trip element.

Ship… Wright?

Read it like “Ship the right way” with an unhealthy dose of name-based puns. Oh, sue me, I didn’t want to agonise over it.

Publishing with AWS Amplify

The code is stored in a public Github repository and is deployed on push using AWS Amplify. Domain hosting is provided by Amazon Route 53.

Configuring hosting and deployment using AWS Amplify is described in the Hugo documentation but out-of-the-box it does fail to account for Hugo Modules, used to provide my Hugo theme, which requires Go to be available.

Following the instructions as provided results in the error described by users in this Github issue that indicates Go is unavailable:

Error: failed to load modules: failed to download modules: binary with name "go" not found

The solution was to configure the Amplify build to install Go prior to running hugo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# AWS Amplify build settings https://docs.aws.amazon.com/amplify/latest/userguide/build-settings.html
frontend:
  phases:
    preBuild:
      commands:
        - sudo yum install -y golang
    build:
      commands:
        - go version
        - hugo
  artifacts:
    baseDirectory: public
    files:
      - "**/*"
  cache:
    paths: []

Writing content with VS Code

For the time being I am content with the writing experience of VS Code thanks to Zen Mode.

That’s all for now folks, thanks for reading. In returning to writing I’m acutely aware of a looming sense that I’m going to churn out some dreadfully shit content while I knock off the rust. Here’s hoping it gets better if I stick with it.