Blogging with Asciidoctor and Hugo

If you want to follow through the whole post, I assume you already satisfied the following conditions:

In most static site generators including Hugo, Markdown is the one and only first-class citizen when it comes to creating posts. However, in recent Hugo versions, there exists the external helpers feature which calls appropriate external programs to certain type of files (or file extension). Fortunately, Asciidoctor-based files are automatically compiled with Asciidoctor so we don’t need to do anything. Just have it installed and you’re raring to go.

Creating content with Asciidoctor

Creating Asciidoctor-based content in a Hugo site is very easy. Just create an Asciidoctor file manually or you could go with Hugo’s way which is the optimal way.

hugo new posts/my-first-post.adoc

And there should be a new Asciidoctor file at content/posts/my-first-post.adoc.

Most likely, you would see that it’s formatted like a Markdown file since most themes do not have focus for Asciidoctor.

One of the features of Hugo is letting you create content templates (or an archetype) for your usual content. We create content with Asciidoctor so let’s create a quick template for that.

Create a file in archetypes/default.adoc. This will be the master template whenever Hugo detects the new content has a file extension of .adoc. Then, create a template for your Asciidoctor documents.

To get an example, here’s my template for my Asciidoctor documents.

-
title: "{{ replace .Name "-" " " | title }}" 
date: {{ .Date }} //
draft: true

categories:
    - "category1"
tags:
    - "tag1"
    - "tag2"
---

= {{ replace .Name "-" " " | title }}
{{ .Site.Author.name }} {{ with .Site.Author.email }}<{{ . }}>{{ end }} 
{{ dateFormat "2006-01-02" .Date }} 

	The frontmatter. Unfortunately, we would still have to put this for Hugo to recognize this document as one of the content.
	Converts the slug of the document to title case.
	Putting the author in the Asciidoctor preamble along with the email (if there’s any). Feel free to discard it.
	The date in ISO format.

Speaking of frontmatters, native Asciidoctor frontmatter is not recognized.

You can modify the template to your heart’s content. For example, if you use MathJax for writing mathematical formulas, you can add the stem attribute (:stem:).

Since Asciidoctor-based documents only recieve basic support, you still need to do some work yourself before you get satisfied with the settings. For example, enabling syntax highlighting and styling certain things like callouts, admonition blocks, and open blocks.

Also, not everything is 100% working so you might encounter some problems which is discussed later in the post. Nonetheless, it works for the most part and you can still write expressively with the heavier feature set of Asciidoctor.

Syntax highlighting can be an important feature for technical blogs especially if you often have to show code in your posts.

On Asciidoctor, you can enable syntax highlighting with the :source-highlighter: attribute. You can compile it on runtime with the executable but it’s not possible with Hugo since the arguments passed to it is hardcoded. You can, however, enable it for every document you have but as you might imagine, it’s not ideal and requires some manual labor.

If you’re only relying on the out-of-the-box features from Hugo (READ: if), you can get it with the highlight shortcode which is going to bite back if you’re going to migrate to another blogging platform or static site generator.

Still, there are some ways with getting syntax highlighting for your Hugo site without the Asciidoctor attribute or the Hugo shortcode. It’ll just take some more effort to get through.

One of the more reliable ways on enabling it is using syntax highlighters like highlight.js or PrismJS. I’ll be discussing on setting it with PrismJS since it easier and that’s what I’m mainly using on my blog.

For future references, the version of PrismJS I’m using is at v1.17.1.

<!-- Inside of the head element -->
<link rel="stylesheet" href="{{ "css/SYNTAXSTYLESHEET.css" | absURL }}">

<!-- ... -->

<!-- Before the end of the body tag -->
<script src="{{ "js/lib/SYNTAXHIGHLIGHT.js" | absURL }}"></script>

While Hugo and Asciidoctor is great and all, there are a couple of problems with this setup.

The most obvious is the HTML output of Asciidoctor with the default backend is not great and leaves a lot of things to be desired.

<div> then a <p> for a paragraph, really?

It’s not semantic and it is unconventional. Not only that it’s a pain to style it with CSS but also breaks a lot of the accessibility features like screen readers since it relies on certain HTML tag structures.

Another problem you could encounter (and maybe bash your head against) is the basic support for Asciidoctor itself if you don’t want to rely much on creating hacks and workarounds.

As previously mentioned, Hugo supports Asciidoctor through external helpers. External helpers are relatively new and more like an experimental feature. There is a proposal on improving it by adding user configurations so at least there’s hope for this particular feature to expand.

There’s also the fact that not all built-in feature of Hugo (such as table of contents) works within Asciidoctor (and possibly other non-Markdown formats) content. Fortunately, Asciidoctor is quite extensive by itself and there’s not a lot of Hugo features that doesn’t work and you won’t likely need them anyway.

Also, native Asciidoctor front matter doesn’t work as previously mentioned.

Some posts are floating around on how to make a done-and-forget deployment toolchain with different tools.

Personally, I pass the full effort of deploying my blog to a CI/CD workflow. I use Travis CI for the job.

Here’s the configuration I’ve used to deploy my Hugo blog:

dist: bionic 
language: generic

before_install:
  - sudo apt-get update
  - sudo apt-get install ruby
  # Assuming that the GitHub API is at version 4.0 
  - curl https://api.github.com/repos/gohugoio/hugo/releases/latest | grep "hugo_extended.*deb" | grep "browser_download_url" | cut --delimiter=":" --delimiter="\"" --fields=4 | wget -qi -
  - sudo dpkg -i hugo*.deb
  - sudo gem install asciidoctor 
script:
  - hugo 
deploy: 
  local_dir: "public/"
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  target_branch: gh-pages
  on:
    branch:
      - demo
      - master

Here’s the breakdown of the configuration:

	It will use a Linux-based machine with Ubuntu Bionic (18.04) as the operating system.
	Downloads the latest Hugo binary from its repo through GitHub release and installs it.
	Installs the Asciidoctor toolchain.
	Build the Hugo site.
	Deploy the build folder to the gh-pages branch of my GitHub repo when the branch occurred at demo or master.

Depending on the web hosting service provider, you may have to do additional work such as pre-compressing your files or configuring your server. Since the blog is hosted using GitHub Pages, I don’t have to configure some stuff (unfortunately for me).

That’s all of the Hugo and Asciidoctor stuff you need to know for now.

Just look for more examples and you’ll get more idea. You can take the GitHub repo of my blog for a starter point.

Personally, blogging with Hugo and Asciidoctor sums up to be fun. So fun that I eventually created a theme that focuses on supporting Asciidoctor content along with other stuff.

Not perfect but it still offers a lot of satisfying and more expressive writing experience compared to writing with Markdown.

With all of the imperfections this workflow has, there’s some stuff to look forward in the future especially with Hugo’s external helpers feature. Hopefully, more tools will take notice of Asciidoctor and how it could be great for writing technical and web-based content.