A lot has changed since I had my last blog. I’ve come across many static site generators over the years mostly in the context of generating documentation. Recently there has been a much bigger move to using static site generators which makes a lot of sense to me. Outside of real dynamic content there is little need for any server side logic or databases.
A few go’s with the Duck Duck and I had more choice than I’d like. If you’re looking for one there a good article on Netlify outlining the factors to consider when making the decision.
Having decided to go this route here are the steps:
- Choose a framework
- Configure the framework
- Choose a theme
- Set up some hosting
- Add some content
- Fiddle
Choosing a framework
In the end I chose Hugo because it was to be highly rated on a few sites and I was taking too much time in making the decision so best to get started with something.
It was very easy to set up and has a good selection of themes.
Configure the framework
The Hugo Quickstart is good but it’s a bit like a “Hello World” in that leaft me with a lot of questions about how it all fits together. With Hugo the motto seems to be ‘convention over configuration’ but it’s not always clear what’s a convention and what isn’t. I also found out later that themes can break the conventions.
One of the reasons I chose Hugo was that it apparently has great docs. I will say that the docs are quite detailed but there’s a lot of nomenclature to get used to.
Choose a theme
This was possibly the hardest part of the whole process. Hugo has a good selection of pre-built themes in the theme catalog and since I wanted something up fast I was not intending to build a theme myself, not yet at least.
Most themes have an example site that you can try out:
git clone <git url> theme1
cd theme1/exampleSite
hugo server --themesDir ../..
Doing that with the promising ones was very helpful since mostly you just get one screenshot on the theme’s home page (if you’re lucky).
Eventually I settled on one and had it installed as a git submodule in no time.
It was then that I realized that the conventions in Hugo are determined in part by the theme. By this I mean that the theme (at least the one I chose) doesn’t have to follow exactly the same conventions as Hugo does in it’s documentation. Also themes seem to be very poorly documented in terms of what they offer.
Set up some hosting
Initially I was going to use Netlify but I realized that you can host for free on GitHub or GitLab (with a custom domain). I didn’t see any other hosting providers that offer a custom domain as part of their free offering so that was an easy decision. I went with GitLab just because I have a few other personal projects there and I really like their set up.
One caveat here is that GitLab has a limited number of free ‘build’ minutes. Once these get used up you are unable to deploy changes to your site until the next month unless you buy additional minutes.
It was very straight forward to get the site hosted. Hugo even have a tutorial on how to do it.
It did take a while to get the custom domain verified on GitLab. They require you to add a TXT record to your DNS to confirm ownership:
_gitlab-pages-verification-code.snopoke.com TXT gitlab-pages-verification-code=***
For some reason it wasn’t getting picked up but a few posts online recommended also adding a TXT record for the root domain:
@ TXT gitlab-pages-verification-code=***
After I did that the verification went through almost immediately and I also found a GitLab page that mentions this approach. I’ll see if I can PR a change to their docs.
Add some content
….. in progress
Fiddle
This is the part where you have everything set up but you want to tweak bits and pieces. I wanted to add a list of tags and adjust some of the styling. Thankfully Hugo makes this really easy to do without having to edit the theme files directly. You can just put files you want to customize in your site folders and Hugo will use them instead of the ones in the theme.
I expect that I’ll be tweaking things for the lifetime of the blog. I do like the way things are set up right now but I’m sure as I get more content there will be things to change. Also the internet is not a very static place, sometimes frustratingly so.