Category: How It Works

I’ve been playing with Jekyll a lot. After WordCamp US, I started toying with the idea of a JSON powered Jekyll site, where WordPress output its posts as JSON and Jekyll pulled in the posts and converted them. This ran into many snags. It wouldn’t be ‘dynamic’ for one, but the biggest issue is that Jekyll’s JSON reading ability was terrible. It didn’t like the complex JSON that WordPress put out.

That sent me hunting down other things like Hugo. Unlike Jekyll and it’s use of Liquid, Hugo uses Go (hence the Go in the name you see).

Installation (on a Mac) is easy.

brew install hugo

Done. It’s harder on my server, but still easier than Jekyll, which started to become a ‘thing’ as I worked through all this.

Using Hugo is remarkably similar to Jekyll except that it works faster and a little more smoothly. The site builds incredibly fast and it dynamically refreshes. So if I edit a post, the page refreshes itself. This let me tweak my theme and posts and sort out the new language incredibly fast. Edit a file, boom, I see what’s wrong.

It’s about as logical as Jekyll too, so it took me one DayQuil addled afternoon to sort out how to make things work.

The Basics

The basic are simple. You have a basic structure like this:

▸ archetypes/ 
▸ content/
▸ data/
▸ layouts/
▸ static/
▸ themes/
config.toml

The config file is what you think it is. Your posts go in content and the html-ized version shows up a public folder that gets created on the fly. The data folder is for your static data like a .json file or a .yaml.

Independant to your theme, you can put css and js in the static folder, and layouts in the layout folder. Ditto archetypes, which are post-types. So if you know you’re always going to have a post type of ‘musician’ and you want it to have special headers, then you can have an archetype called musician.md with all that pre-filled in. Then when you want to make a new entry for Clifford:

$ hugo new musician/clifford.md

You can also have those in your theme if you wanted, but generally I use the same theme and separate projects. At this point, I was impressed enough to be swayed from Jekyll. I’m not going to explain how to write a post, since it’s just markdown and a header, just like Jekyll or GitHub Pages.

Building Your Site

The commands are basic. Running $ hugo server will build your demo server. Of course, you’ll want to post your drafts, so you need to add the param --buildDrafts … Oh and you want a theme …

$ hugo server --theme=utility-pro --buildDrafts

That’s silly, right? Why do I have to define all that? Thankfully I can edit my config.toml file:

baseurl = "http://example.com/videos"
languageCode = "en-us"
title = "My Super cool Video Library"
theme = "utility-pro"
buildDrafts = "true"
[params]
Subtitle = "Videos about cats, collected from the internet."

Now every time I run the command ‘hugo’ it will build my drafts with my theme!

$ hugo
45 of 45 drafts rendered
0 future content
45 pages created
42 paginator pages created
14 tags created
3 categories created
in 254 ms

That’s incredible fast seeing as it built everything. Of course the other site I have is a great many more pages.

Theming

Since I’d already mastered Jekyll theming, this was trivial. Go and Liquid are weirdly similar and most of it was transposing. There’s not much to say here except that there’s a Twenty Fourteen Theme for Hugo and it’s pretty much what you expect. For WordPressers, it’s a good place to start.

Shortcodes

The neat thing is that Hugo has shortcodes! They’re not like WordPress ones, but you can see the similarity between WordPress and Hugo.

[video mp4="video.mp4" flv="video.flv"]

vs.

{{< video mp4="video.mp4" flv="video.flv" >}}

Sadly there’s no oEmbed. And I had to write the shortcode on my own, but again, if you know the basics of logic all this stuff is easy. Here’s the magic behind the shortcode:

<video class="video-js" width="{{ if .Get "width" }}{{ .Get "width" }}{{ else }}640{{ end }}" height="{{ if .Get "height" }}{{ .Get "height" }}{{ else }}385{{ end }}" controls>

	{{ if .Get "mp4"  }}<source src="{{ .Get "mp4" }}" type="video/mp4">{{ end }}
	{{ if .Get "ogg"  }}<source src="{{ .Get "ogg" }}" type="video/ogg">{{ end }}
	{{ if .Get "webm" }}<source src="{{ .Get "webm" }}" type="video/webm">{{ end }}

Your browser does not support the video tag.
</video>

Once you look at it, it’s remarkably like WordPress. Only I don’t need a plugin. Everything in /layouts/shortcodes/ are like mu-plugins.

And So?

And so Hugo won enough of my attention that I’m going to keep playing with it and see what’s next.