Andy Thornton

Vintage English Pluviophile, Bemused New American, Open Source advocate

A place to ramble on the internet.

Using Asciidoc for Web Development

During the day, I work with content management tools and support documentation writers who’s preferred language of choice is Asciidoc. It has a simple syntax, but enough features to keep even a hard core documentation nerd happy. With Asciidoc, you can write documentation in a more natural way and mark it up cleanly for presentation on the web or as a PDF. This got me thinking, "Wouldn’t it be handy to be able to maintain a website purely with Asciidoc?"

Some quick Googling and chatting with colleagues and I was introduced to Hugo which is a publishing platform which can transform articles written in MarkDown or Asciidoc into usable content for the web. The platform has a rich language for working with templates and theming. As well as organising content and can be used to build a blog with enough functionality to keep me happy, but without the need for a database. The pages are rendered HTML so the site is blazingly fast and very easy to maintain. It even comes with it’s own server so I can test my site while I work on it.

The lack of a database or the need for a language such as PHP makes it especially handy if you’re working on a site relating to security by reducing the risk of SQL injection. It also means the website is much faster than a traditional blog platform. As long as your server can deliver HTML, you’re good to go. Combining this with a CDN and you have a very fast website.

Hugo also supports tasks which are normally driven by your blogging platform, such as RSS feeds which can be generated automatically when a new article is added. You can maintain articles in a "draft" state which will show up on your local machine, but won’t be published until you mark them as ready for the world. Combining this with a Git branching strategy means multiple authors can work on articles and book them back into your main branch when ready to publish. Everyone can run a copy of the site locally while they work on their articles. Other interactive elements such as comments, can be included using disqus. Hugo is a very feature rich platform and a lot of fun to work with.

When I work on a blog, I approach it with the idea of "Content First" and try not to get tied up with working on the platform. Which is a fine idea, but the reality is that I find myself constantly tweaking the site. Then I tweak it a little more, then a weekend is gone and I haven’t written anything! I ended up just playing with the theme or working on back end services. Hugo has a decent template system and I can do a lot more with a lot less code. Because my articles are written in Asciidoc, I can focus on content rather than presentation. Asciidoc helps me write a document with a nice structure and through the use of Asciidoctor, I can convert the pages into other formats. Such as PDF or Linux manpages. so I can preview them locally as HTML.

Asciidoctor is a digital swiss army knife for Asciidoc. Hugo uses Asciidoctor to convert the documents as you write them. It also helps me identify places my content needs work. Running Hugo in a console, I can see issues with my document whenever I save it. So I can fix them and move on. Which is different to my usual routine ..

My blog post is done! and now to send my masterpiece to the world! …​. wait a minute, why is all my text a H1…​…​ I hate myself.

— Me at 3am on very little sleep and too much coffee'

Documentation workflow

I normally write my first drafts in plain English, to get everything started. I use a new branch in git for each article which keeps things nice and simple until I am ready to publish. Once I have that done and given it a couple of passes to make sure everything flows well, I add asciidoc markup so Hugo can format the article as clean HTML. When the article is ready to publish, I merge it back into my master branch.

If I need to add the same text repeatedly, I use an include to contain boilerplate text as reusable content. These can be setup in my template or I can define content types which automatically add them depending on the type of page I am working on. I can include a standard license statement or a paragraph about getting support if I am writing a techinical article. It’s also handy if This is handy if you are writing a document with standard sections, such as a company description, or an installation guide. You can insert them into your document making it more modular and easier to maintain.

You can also define metadata which can later be used by your theme to help organise content. Tagging articles and grouping content as an example. Handy if you want to define a page as a "solution" or a "FAQ". The template language provides a feature rich system for grouping and working with content. This is especially handy with Asciidoc as the header of a document will have standard metadata section which may be different between an article and a blog post. I can define them within Hugo and it does the work for me when I create a new piece of content.

Working with Asciidoc

My default editor of choice is Vim, which has syntax files available for Asciidoc. If you are looking for a more visual approach to working with content, I would recommend the Atom editor with an asciidoc preview plugin which makes working with Asciidoc very easy. It helps check your document as well as provide a real-time preview of your page. As the editor was created by GitHub, it has built in support for working with Git, so working on documents across different branches becomes straight forward.

Atom Editor with preview plugin
Figure 1. Atom Editor, click for full screen

Overall, I am very happy with Hugo and Asciidoc. My process becomes more "content focused". I have a great work flow with git and the performance on the site is noticeable when compared to a traditional php / mysql CMS.

How can I play with this setup?

If you are interested in getting started with Hugo and Asciidoc, I put together a demo website with content and a theme along with notes on how to get up and running. It is available from the Opensourceway’s Github page. Rather than filling this article with step by step instructions on how to download and configure Hugo and how to write with Asciidoc. I have put notes into the website along with links to resources on-line to help get you started.

Have fun with Asciidoc and Hugo, post links in the comments to any projects you produce with Hugo.

« Return to homepage