Hugo For The Semi Literate Techie

I am a semi-literate techie. I deal with hardware in my day job and software is a hobby on the side. So while I can hack code and generally come up with a solution to my problem, I can’t whip up a site like Gmail or Stackoverflow over a weekend.

I originally started on Blogger and decided to try Hugo after I had concerns about Google’s long term plans for Blogger. We have seen with sites like Picasaweb and Google Reader that Google has a tendency to close sites that are not updated often.

I chose Hugo over its many other static blog competitors because it has a very simple setup – it is a single native executable that runs on all the major OS’es without dependencies. There is no need for gems, rakes, Ruby, or any external software.

I chose a static blog because I want to simplify hosting. I do not want a server that requires securing and patching, a database I have to maintain, or dealing with upgrades. I want portability in case I have to switch to a different webhost or different blog engine.

I host my Hugo site on Amazon S3 and push it through CloudFront for about $1/month. Cloudflare is another good free option. With CloudFront, the site is replicated all over the world and will scale rapidly if I experience a blowout. Also I don’t have to deal with maintenance or censorship. If Amazon objects to my content or disappears then I’ll simply move it to another web host.

Some of the startup pains I, the semi-literate techie, have encountered:

  • Many of the themes seem to be broken.
    • For example, themes like (Bootstrap, Tachyon) only recognize a directory called ‘post’. Logically a directory with many posts should be called ‘posts’ but this has escaped the theme writers.

    • I tried the Tachyons theme but it gave me an error message when I created a new post. If I was a Go literate programmer I’d figure out a fix and submit a patch to github, but I am not a programmer and a theme that breaks when you do something basic like create a new post really shouldn’t be a so-called featured theme.

    • Themes do not appear to be inter-operable. I started with Bootstrap and got error messages when I changed the theme in my config.toml. Again, I really don’t want to debug error messages when publishing to my blog.

  • Hugo is very particular about its base path. I couldn’t simply put hub.nexms.com but had to use http://hub.nexms.com. Seriously, does it think I’ll be serving this site over gopher://?

  • Hugo uses a non-standard markdown processor. Instead of using GitHub markdown or CommonMark, it uses a library called BlackFriday. This means we have to deal with idiosyncrasies unique to this parser – for example, tables are formatted differently on BlackFriday than on GitHub. Table support in Markdown is universally bad. I eventually gave up and coded my tables by hand in HTML.

  • The themes or Hugo are not optimized for speed. Using the Google PageSpeed Insights tool shows:

    • The JS and HTML content could be minified to reduce download time
    • The CSS could be inlined for faster loading

There is no easy Markdown convert and view flow. This means I have to run my markdown file through Hugo and open it in a web browser to see my changes.

I use stackedit for my Markdown editing. Stackedit runs in the browser, shows my Markdown and final view side-by-side, and syncs my files to Google Docs. This makes it cross-platform and usable on all my computers. I still have an annoying flow where I have to copy the Markdown into a text file with Hugo headers before publishing.

To sync my files to S3, I use Jets3t. Jets3t is cross-platform and comes with a highly configurable utility called synchronize which lets me automate the upload. The best part is that I can enable SHA256 encryption with a single line. Now my files are encrypted while in storage at S3 and only decrypted when sent to the browser.