Setting up a Hugo blog with Netlify

This year before BrightonSEO, I spent a lovely day in the bottom of a dark pub with a bunch of smart people at ohgmcon (a small conference/get together run by Oliver Mason).

Tom Bennet gave a presentation about the JAM stack and his pitch for why it's the future. I've been putting off making a blog for ages and this seemed like a good opportunity to create a static site.

It's live now (as you may have noticed), so here are my thoughts on the whole thing.

Summary

Would I recommend the Netlify + Hugo combo for a blog? Yes, as long as you're relatively technical. You'll need to be able to look at a command line with panicking.

If you're not I'd stick with Wordpress at the moment.

Benefits

• It's really really fast. Even with all the JS my pre-built theme came with, it's fast.
• I don't need a worry about security, because my blog will realistically never need a backend.
• Netlify offers a lot of excellent one click server side features like HTTPS which were lovely and easy to set-up.
• I like having everything hosted on Github. It gives me a natural back-up. (With the caveat, that Github is still a single point of failure.)
• Although theme/boilerplate dependent, there are some nice one click integrations like Disqus.

Negatives

• It still feels new compared to incumbents like WordPress. There is no good way to find themes; I had to add basic SEO requirements myself and the documentation was occasionally opaque and hard to follow. (That's mostly Hugo criticisms.)
• If you want to customise your theme, you're going to need to be familiar with some JS development workflows. This didn't seem as immediately friendly as PHP had been (although this may be curse of knowledge now).
• If you're not already familiar with Git & the command line I suspect this whole process will be notably more scary. Although on the flipside, if you are comfortable with this then this is possibly a plus.
• Compared to other Markdown editors I wasn't particularly impressed with Netlify CMS out of the box.

Fancy giving it a go? Read on.

What is what?

• Hugo - A static site generator. It takes content and templates and turns them into a set of HTML pages.
• Netlify - A place to host a website created with a static site generator.

Basic Set-up

This part wasn't too bad. I managed to follow the instructions here without issue.

Main learning points

• The /site/ is where all the development happens. When you run the server, it's all built and served from /dist/.
• Until you add a theme virtually all the customisation happens in config.toml or in the posts themselves.

Picking a Theme

Gotta go read all that theme documentation. There was no quick win I found for finding a good theme, sorry all.

Adding a theme

How to it:

• Download or clone a theme of your choice into /site/themes/
• Set theme in config.toml - theme = "my_theme_name"

• If you've cloned a well maintained theme to get updates and want to customise it past the in-built options, you'll need to fork it into your own repo so Netlify can use that as the sub-module or work with the theme owner to fork/contribute to the original repo.

  • Aside: A sub-module is where you have one git repo hosted inside another. I had not encountered this before. Useful SO thread.

Problems installing node-gyp on Windows

I wanted to customise my theme past the in-built in options and so needed the ability to build it. The theme required node-gyp, which has a couple installation issues on Windows.

I have Anaconda 3 installed as my default version of Python, this clashed with the node installer and I had to manually set the python environment.

npm config set "python" "C:\ProgramData\Anaconda3\envs\py27\python.exe"

Node-gyp also needs Visual Studio Build tools. Don't you just love developing on Windows?

npm install --global windows-build-tools

Server hang-ups on theme installation

When installing the theme I ran into an error, where on npm start the server would hang and fail silently:

	* [17:01:27] Starting 'js'...
	* [17:01:27] Finished 'css' after 1.12 s
	* [17:01:27] Finished 'hugo' after 1.14 s
	* [17:01:27] [webpack] Hash: 417ac7d4d4addd6cba3c
	* Version: webpack 2.7.0
	* Time: 156ms
	*  Asset     Size  Chunks             Chunk Names
	* app.js  2.89 kB       0  [emitted]  app
	* chunk    {0} app.js (app) 139 bytes [entry] [rendered]
	*     [0] ./src/js/app.js 111 bytes {0} [built]
	*     [1] multi ./js/app 28 bytes {0} [built]
	* [17:01:27] Finished 'js' after 315 ms
	* [17:01:27] Starting 'server'...

This seemed to happen sometimes when I referenced something that didn't exist - like a theme.

Having a nice place to write

I installed Netlify CMS (following the quick start, no real issues), but it's not a wonderful experience.

I didn't enjoy working with a split of markdown and rendered markdown and the whole thing felt a little new and lacking.

If I'm going to write more, I want to enjoy it, so out went Netlify CMS and in went Typora.

It's a great experience. Markdown switches to rendered markdown as you write it and it's a clean distraction free experience.

It's free until the beta is up, then paid for. At which point I will quite happily pay.

Learning Build Tools

Aside: This isn't required for a static site in Hugo, however I was using the Victor Hugo boilerplate, which does come with all that.

This was probably the biggest learning curve for me. If your background is in the traditional Wordpress, Drupal etc. then there's a reasonable chance you might not have encountered many JS workflow tools before.

For example: in Drupal I've traditionally handled everything with AdvAgg, I upload CSS and all the minification and aggregation is done server side.

With a static site generator, all of that is of course done locally as part of the build process. Victor Hugo uses a combination of Webpack and Gulp, I was familiar with neither.

I'm sure in time I will grow to love them, but currently a keen eye, may notice my CSS & JS is not quite as minified as it probably should be...

SEO Customisation

I am using the Theme TranquilPeak. It looks lovely, but from an SEO point of view has a couple issues.

Pagination

It doesn't come with any, but I also don't have enough posts to have to fix it yet. When I do I will come back and update.

No-indexing pages

There's nothing built in and while it's easy enough to add a variable to no-index posts, I couldn't work out how to do so cleverly for all the other bumpf pages it generates like taxonomy and category pages.

The temporary solution has been to generate an alternate head template which contains a no-index tag, so I now have:

• head.html
• head_alternate.html

Canonicals

No-inbuilt canonicals, this was easily solvable by adding it to the main head.html.

<link rel="canonical" href="{{ .Site.Params.protocolDomain }}{{ .URL }}">

Dates in the URLs

For news-worthy and time sensitive content, I actually quite like having the date in the URL, it provides a strong signal both visual and semantically about the importance of time to the page.

Clearly everything I write is timeless though, so the last we want are dates in the URLs.

This one was also nice and easy to fix, under the permalinks section of config.toml, you can set the URL structure:

# Before
[permalinks]
	post = "/:year/:month/:slug/"

# After
[permalinks]
	post = "/:slug/"