Introduction
This post is about how I set up this site!
Framework
So I wanted a static site generator. You know, the trendy, ‘lightning-fast’, modern-web-has-gone-full-circle technology. Because I just want to write some text that people can read, and I can execute a build step without hurting myself.
Perfect is the enemy of good
Knowing I’m the kind of person who often lets perfect get the better of me, I didn’t want to get stuck at step one this time.
I took the top three static site frameworks from stackshare : Jekyll, Gatsby, Hugo. And whittled them down through opinionated first-impressions and prejudices:
- Gatsby is react-based and seemed to be peddling JAMstack ‘webapp’. This sounded a lot like ‘JavaScript bloat’ for a blog use-case.
- I’d used Jekyll once before, and for my chosen theme I had to commit some file dump and modify the theme files directly. Maybe this isn’t always the case, but my experience scarred me. No theme updates?
- Hugo is like Jekyll, but new, and Go 🥰.
Setup
Being on mac, installing Hugo with homebrew is breezy:
brew install hugo
And following their quick-start was straightforward enough.
After my Jekyll experience I was delighted to find themes are tracked as git submodules. Themes are swappable and updates are easy! 🙌
Deployment
Netlify misfire
I had assumed I’d host for free with netlify , another trendy platform where Hugo is a first-class citizen.
But after linking to my GitHub repo and configuring the build command I was greeted with:
Transformation failed: POSTCSS: failed to transform “css/main.css” (text/css): PostCSS not found; install with “npm install postcss-cli”. See https://gohugo.io/hugo-pipes/postcss/ 2
It turns out my chosen theme (Call me Sam - what a narcissist!) depended on the PostCSS Hugo Pipe , which meant I needed some npm packages installed globally.
Whilst I could fix my local build like this easily enough, it was less obvious where to do this with Netlify. Was node preinstalled? Can I execute multiple build commands?
If you want a job done right…
I decided to take control of the build pipeline myself. Who knows what future dependencies I might want? If I had to learn some platform-specific configuration, I’d rather use one where I knew I couldn’t hit a brick wall.
So I built the site in a CircleCI pipeline and deployed to GitHub pages. I like CircleCI because you can use docker images for each job, unlike e.g. Travis, which can save some time installing dependencies.
After following some instructions , the job that pushes to GitHub pages announced:
ERROR: The key you are authenticating with has been marked as read only.
Clearly I’d lost patience reading, because the ‘Provisioning a deploy key’ section contained it all. Once I created a new key and gave the public part to GitHub and the private to CircleCI I was in business! Seriously, take your time with that article, it has everything you need.
You can see the pipeline config here in all its glory.
Conclusion
And there we have it! A Hugo site, built on CircleCI, deployed on GitHub pages. The internet has yet another blog.