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.

Gemfile

source 'https://rubygems.org'
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