Initial Setup

Hugo has built-in support for AsciiDoc but cannot render AsciiDoc files to HTML on its own. To be able to write blog posts using AsciiDoc, install Asciidoctor (recommended) or AsciiDoc:

$ gem install asciidoctor

$ pip install asciidoc3

Netlify Continuous Deployment

Netlify uses Gemfile and Gemfile.lock to install Ruby dependencies automatically. To use AsciiDoc, you will need to create a Gemfile in the project root directory with the following contents:

source 'https://rubygems.org'
gem 'asciidoctor'

To create a Gemfile.lock, install the bundler gem locally (gem install bundler) and then run bundle install. Add the lock file to your git repository and push it.

Lock Files

A .lock file is primarily for keeping track of the last tested versions of your project’s dependencies. The Gemfile is a list of package names, whereas Gemfile.lock specifies specific versions to prevent breakage due to updates in production. Pipenv works much to the same effect for Python projects, but also manages virtual environment and keeps track of dependency hashes for security, among other useful things.

Writing Posts

The first difference to note is the file extension used, AsciiDoc files must end with .adoc or .asciidoc. Read up on the syntax then create a new post with Hugo by running hugo new posts/post-name.adoc and start writing.

Headers

Note that only one “level zero” (h1) header is allowed in any AsciiDoc document not specified to be a book. Hugo already makes a h1 element from the title sent in the front matter, so your post’s first header should be a “level one” (h2) header:

== Header title

notice the two equal signs, this is important.

Front Matter

Note that all types of front matter in Hugo are compatible with all supported content formats. The hugo new command uses YAML front matter formatting by default, but none of the other options (JSON, TOML, Org) will cause issues with AsciiDoc.