Intermediate Content Authoring with Hugo

If you read my previous post you know how impressed I was with the performance of Hugo and the minimal ramp-up time needed to get a site up and running.

I was less thrilled with the content authoring itself. To clarify why, I’ll describe my use case a bit…

I’m looking to do a simple tech blog on the cheap. I am comfortable with bash/git/markdown and happy with a developer-centric content management approach in general. I want to start authoring and posting visually-appealing content as quickly as possible. To me, visually-appealing means images, formatted code fragments, and videos in addition to text content. I may want to invest more time in the future, but for now I’d really rather not have to spend a lot of time messing around with HTML templates, CSS or Go in order to make this happen.

While I got stuck at the basic text part, it turns out the rest is plenty easy to do with Hugo. It’s just buried in docs and forums. It took a few days of hunting around before I figured this out. Hopefully, this post will help bring some of this information to the fore.

Using Hugo Page Bundles

You may recall that in my original post I created my new page like this:

hugo new posts/building-this-site.md

Then I added a folder to the “static” directory called “img” and referenced images in my posts like this:

![Configuring the Azure portal](/img/azure-portal-setup.png)

While it worked well enough, the approach has the downside of not closely tying content with the resources associated with it. Page bundles to the rescue.

Page bundles create a folder per post, grouping an index.md file with its associated assets. This keeps things logically organized which should make maintenance easier in the future.

All that was required to make this approach work was to use a hugo ‘new’ command like this:

hugo new posts/building-this-site/index.md

Now I can drop images in the newly create folder and include them in my markup with a relative path URL. Beautiful. I refactored my original post to use this structure.

Using shortcodes in Markdown

The next revelation was shortcodes. It wasn’t immediately apparent from the documentation that these are intended to be used in Markdown files, but they are and they are fabulous. Some of my favorites…

figure

Using the figure shortcode you can include a formatted image. This lets you set attributes such as the width so all your content doesn’t scale if you don’t want it to.

{{< figure src="kiddo.jpg" title="The author's kiddo" width="50%" >}}

In the case of the figure shortcode you can even specify a CSS class for the image if you want to do some more advanced styling.

relref

The relref option let’s you create internal links such as this.

{{< relref "building-this-site" >}}

Note that you do NOT need to treat these paths like directories. That is, Hugo appears to consider you to be on a posts page with one name (e.g. more-hugo) accessing another posts page (e.g. building-this-site). There is no need to reference .md extensions or include trailing directory slashes.

youtube, instagram, twitter

There are shortcodes for many of the major social networks. These let you include media or posts knowing only the ID of the content. Here is an example using the youtube shortcode.

{{< youtube NSts93C9UeE >}}

param, gist, or make-your-own

There are a few other shortcodes I imagine I would be interested in just as param which lets you access variables in front matter or gist.

It’s also worth noting that you can create your own shortcodes if there is some custom markup you found yourself frequently embedding in your pages.

Odds and ends

I’m using VS Code as my markdown authoring environment which has it’s pros and cons. One of the latter is that there is no default spell-checker. I installed an extension called Spell Right to get the functionality. I’d love to get some grammar checking in place as well, but it appears the options there are more limited.

Final thoughts

The above techniques really do make Hugo a much more viable tool for a personal tech blog. I may want to try using a static-site CMS at some point soon but I’m guessing that I currently have most the functionality I need without one.

Now that I have a couple posts under my belt I’m thinking about other things I can do to improve the website. Some thoughts for next steps include further customizing the CSS, including new fonts, switching themes, creating a custom shortcode, modifying or adding new templates and/or content types.

I’ll be sure to blog about these if I do…