Renovating my site with Hugo

I finally carved out some time to finish redesigning my site. I’ve moved it off Wordpress, now it’s a static site generated by the Hugo site generator. Here are my experiences with it:

Hugo Pros:

  • Easy to install. It is a command line tool, mind you.
  • It’s quite general. Seems to impose fewer blog-shaped conventions than Wordpress.
  • The auto reloader is fast and works well. Remember to turn off caching in developer tools though, because otherwise you’re not gonna see CSS changes.
  • Even a full rebuild takes under a couple of seconds for me.
  • Although it says posts should be in Markdown, you can totally feed it Wordpress’s weird whitespace sensitive HTML and it basically works fine.

Hugo Cons:

  • The expression language inside the templates is kinda odd. Prefix notation for everything. Scoping has some surprises.
  • I’m not seeing an ease-of-use dividend from posts being Markdown instead of template HTML. Switching between two dialects of not-quite-HTML is confusing.
  • You can define functions for use in templates (“partials”), and define them in Markdown content (“shortcodes”), but they’re different kinds of functions and aren’t interchangeable.
  • Putting stuff below the fold via Read More buttons is a mess. There’s a Summary property for the portion before <!–more–>, but if the fold tag is absent, it produces a yucky auto-generated summary which has all the formatting stripped. Even the paragraph breaks! And there’s no way to tell if Summary is garbage or not, so it’s simply unsafe to use.
  • Viewing content by tag: built into Hugo.
    Viewing content by type: built into Hugo.
    Viewing content by year: theme surgery.
  • I started from a rather maximalist theme called Icarus, and that was probably a mistake. It would’ve been an easier learning experience adding stuff to a minimalist theme.
  • Sometimes when theme authors say “minimalist”, they just mean lots of whitespace. Check the network tab of developer tools and see what’s really going down before picking a theme.
  • The documentation encourages you to use file-by-file overrides to customise a theme. This quickly gets very confusing if you’re doing anything substantial. I say just gut the thing. Merging upgrades manually seems easier than continually dealing with brittle partial directories of overrides. Hugo is already a mess of union filesystems before you start putting overrides on the top of that.

Misc. Awkwardness:

  • The Wordpress-to-Hugo exporter is a Wordpress plugin. If you’re using, it’s on you to write a convertor script that processes the export XML.
  • I miss having a UI for recategorising posts en masse.
  • Disqus sucks. It’s hard to find an alternative though. Not Hugo’s fault, but something to bear in mind if you’re going static.

Would I recommend it? If you find a theme that does exactly what you want, it’s OK. If you have to customise, you’re probably going to lose a couple of weeks poking around byzantine nonsense.

I can’t shake the feeling that somewhere there’s a team working on an Offline Site Generator for regular civilians. Not just a word processor with HTML export, but a whole offline CMS. I suspect once they release, the Hugos, Jekylls and Octopresses of the world will look curiously old fashioned.

Share Comment Forum