When I needed another outlet to begin blogging about another product we’re working on, I reached for another standard WordPress install. It’s what I’ve come to know over the past couple years and while I’ve never felt satisfied with it — it worked well enough to let me focus on writing.
Before I started the WP install, though, I took a few moments to consider what functionality I really needed: HTML templating, analytics, and a comfortable way to draft content. I’ve never been able to achieve that last one with WordPress. Writing in the WYSIWYG editor, even in distraction-free writing mode just wasn’t enjoyable. Copying and pasting my content from another source like Google Docs or https://draftin.com/ into the editor was disappointing to say the least.
Static Site Generators
I started reviewing static site generators, since they really do fit my current list of criteria. A static site generator would eliminate the load issues I was experiencing with WordPress that was forcing me to use caching plugins to avoid fetching content from MySQL on each page load. I would also be able to simply host the entire blog in S3 and serve content from CloudFront. The only missing component would be comments — which I felt I could forego until I’ve had time to review services like Muut, Disqus, and the like.
I’ve used static site generators like Jekyll in the past, but the Ruby dependencies were always disappointing. Granted, most modern day developers will have Ruby, RubyGems, and NodeJS pre-installed on their machines. Being a Python developer, I looked at Pelican, but it left me with a similar feeling as Jekyll.
Go
Over the past few years I’ve been writing a lot of Go. Most of the projects I’ve worked on in the past 2 years have had a significant portion of them written in Go and I’ve grown to embrace the idea of static binaries, extremely fast builds, and the world of Go interfaces. When I came across Hugo it seemed only natural to give it a try.
A single static binary means no external dependencies, and while I do have the Go compiler installed on my machine, it’s not a requirement (since you’re not actually compiling any Go code). Like other static site generators, Hugo can be setup with a configuration file and it parses layout files (HTML templates) and your Markdown into a final set of public assets and HTML documents. Hugo‘s built-in web server allows you to preview your content locally while you’re writing it and a single configuration setting lets you easily switch between themes.
Since I chose to deploy to S3, the deployment process couldn’t be simpler. After creating a bucket, choosing the “static website” setting, and adding a public-read bucket policy, pushing the static is a single aws s3 sync public/ s3://blog.cronally.com/. Done.
Markdown
If you use GitHub you’re familiar with Markdown. It’s lightweight, plaintext, and can be turned into HTML with some tooling. If part of your content writing process involves hopping in and out of HTML source (like mine) and adjusting the HTML when necessary, you might find writing your blog content in Markdown somewhat frustrating at first.
A really useful feature of Hugo (and possibly other static site generators) is how simple it is to create shortcodes. Shortcodes make it incredibly simple to create reusable HTML snippets that can render on their own, or wrap other content. Want to make a bordered container with a light background to display some content inside for emphasis? Create a shortcode. Want to embed a video or bit of JavaScript at a particular point in your content? Create a shortcode. Since I use GitHub gists fairly often, I wanted an easy way to embed them in my Markdown. Here’s an easy way to do just that.
Links
I use a lot of links in my content to reference external websites, blogs, GitHub repositories, etc. WordPress supports the Command + K shortcut to make adding links easier, but I still have to find the link, copy it, press the shortcut, paste it, and press enter. When you’re inserting lots of links, that becomes fairly tedious. With Markdown you can create links at the top or bottom of your page and then reference them later by using an identifier:
[g_link]: http://www.google.com Now I can link to [Google][g_link] as often as I need to and just refer to the top of my post for the identifier. Even better, these declarations won't be rendered into HTML content until they're used.
Code Samples
I also post a lot of code samples. While many of them use GitHub gists, for one-line snippets it’s often a hassle to create them. My current method in WordPress is to switch to source view and wrap my code in <code> or <pre> — which usually works, but is often finicky, forces me to add HTML after the ending tag if I want to continue writing non-code in visual mode afterwards, and tends to slow down my writing. Writing in a format that has tooling to natively support code samples makes this process much easier.
The new blog is just getting started, but feel free to drop by and let me know what you think!
Leave a Reply