AsciiDoc support for Hugo on Netlify

When trying to publish my post yesterday I had my first experience with a failed build. Looking at Netlify’s deploy log it was quite obvious what happened: Hugo on Netlify didn’t have the AsciiDoc helper. Here’s how to fix it.

The error message in the deploy log was pretty straightforward:

5:11:50 PM: Executing user command: hugo
5:11:50 PM: Building sites …
5:11:50 PM: ERROR 2019/09/18 07:11:50 asciidoctor / asciidoc not found in $PATH: Please install.
5:11:50 PM:                   Leaving AsciiDoc content unrendered.

The post was the first I wrote in AsciiDoc instead of Markdown, and Hugo’s AsciiDoc external helper wasn’t installed yet. It’s an easy fix, couldn’t find a clear article about it though hence this blog post.

Netlify’s buildbot can install software on build, all you need is a Gemfile in the root folder of your project pointing at the right software packages, in my case that’s just asciidoctor.


source ''
gem 'asciidoctor'

Then update Netlify’s build settings from hugo to bundle && hugo. Once the Gemfile is added to the repo the next deploy should succeed and your AsciiDoc-written posts will emerge.

Netlify Build

Related Articles

comments powered by Disqus