How to create a blog with AsciiDoc

Combining the AsciiDoc markup language with the Hugo publishing platform produces fast, easy-to-maintain websites and blogs.
584 readers like this.
A introduction to creating documents in LaTeX

I work daily with content management tools and support documentation writers whose preferred markup language is AsciiDoc. It has a simple syntax, but enough features to keep even a hardcore documentation nerd happy. AsciiDoc allows you to 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?"

After some googling and chatting with colleagues, I found Hugo, a publishing platform that can transform articles written in Markdown or AsciiDoc into usable content for the web. It is a very feature-rich platform, with a rich language for working with templates and theming, and it's a lot of fun to work with.

One big advantage to me is that Hugo doesn't require a database to support a blog site with plenty of functionality. The pages are rendered in HTML, so sites are blazingly fast and very easy to maintain. It even comes with its own server, so I can test my site while I work on it. As long as your server can deliver HTML, you're good to go.

The lack of a database or need for a language such as PHP reduce the risk of SQL injection, making it especially handy for creating secure sites. It also makes a website faster than one on a traditional platform, and combining it with a content-delivery network (CDN) produces a very fast website.

It supports tasks that normally are driven by a blogging platform; for example, it can automatically populate an RSS feed when a new article is added. Everyone on your team can run a copy of the site locally, so they can work on their articles in a draft state and refrain from publishing them until they're ready. If you combine it with a Git branching strategy, multiple authors can work on blogs and articles, then book them back into your main branch when ready to publish. Other interactive elements, such as comments, can be added with Disqus.

A different kind of development platform

When I develop a blog, I start with the idea of "content first" and try not to get tied up with the platform. This is a fine idea, but, in reality, I constantly tweak the site. Then I tweak it a little more, then a weekend is gone, and I haven't written any content. I spent all my time playing with the theme or working on back-end services.

Using the Hugo platform with the AsciiDoc markup language and AsciiDoctor, a digital Swiss Army knife for AsciiDoc, helps me focus on content and structure rather than presentation. Hugo has a decent template system, so I can do a lot more with a lot less code. AsciiDoc helps me write documents with a nice structure, and Hugo uses AsciiDoctor to convert the documents into other formats, such as PDF or Linux man pages, as I write them. Because I can preview them locally as HTML, I can identify places my content needs work. By running Hugo in a console, I can see issues with my document whenever I save it, so I can fix them and move on. This is different from 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 3 a.m. on very little sleep and too much coffee

Documentation workflow

I normally write my first drafts in plain English. I use a new branch in Git for each article, which keeps things nice and simple until I am ready to publish. Once I give my article a couple of edits 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.

Often I work on documents that include standardized text or content (e.g., information about licensing, support, or company descriptions). I use an include statement for that boilerplate content and set it up in my template or define content types to add it, depending on what I'm working on. This method makes standard, repetitive content more modular and easier to maintain.

You can also define metadata that your theme can use to organize content, e.g., tagging articles, grouping content, defining a page as a "solution" or a "FAQ," etc. This is especially handy with AsciiDoc, as a document's header will have a standard metadata section, which may be different between an article and a blog post. I can define the metadata within Hugo, and it does the work for me when I create a new piece of content.

My preferred editor, Vim, has syntax files available for AsciiDoc. If you are looking for a more visual approach to working with content, I recommend the Atom editor with the AsciiDoc Preview plugin. It provides a real-time preview of your page, making it easy to check your document. Atom was created by GitHub and has built-in support for working with Git, so it's straightforward to work on documents across different branches.

Atom editor

Overall, I am very happy with Hugo and AsciiDoc. My process is more content-focused. I have a great workflow with Git, and site performance is noticeably better versus a traditional PHP/MySQL content management system.

Getting started

If you are interested in getting started with Hugo and AsciiDoc, my demo on GitHub provides content, a theme, and notes on how to get up and running. The README also contains step-by-step instructions on downloading and configuring Hugo and writing with AsciiDoc, as well as links to resources to help you get started.

Have you used AsciiDoc and Hugo? Please post links to your projects in the comments.

User profile image.
Perfume addict, tinkerer, retro gamer, security enthusiast and opensource advocate. Passionate about privacy, ethics and technology. Code slinger at Red Hat.


Thanks for posting this. I recently found out about Hugo and wanted to give it a try, so the article is right on time :)

One thing that is not really clear to me yet: can Hugo work in a "mixed" mode, where I have static content pages (bio, documentation, ... ) and also have a /blog/ section where my blogging would go?

You can create a folder for static content and include an index page, so if you want an about me page, create a folder called "about" and add an index page, so it would look like this "content/post/about/index.adoc" that will show up under /about on your page. There's a lot more you can do with url aliases which can be defined in the header on a document, I found it nice and simple breaking them out by URL so editing them was easier. In the demo on github all the content is under content/post/, but there's no reason you can't break it out under a folder like "content/post/blog" and store your repeating content in there and then use a template to format the as a blog list. Hope this helps.

In reply to by pilhuhn

I'm using Wordpress on my blog
On PHP & Mysql as normal.
Should I give this method a try soon?

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.