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
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
Add the lock file to your git repository and push it.
.lock file is primarily for keeping track of the last tested versions of your project’s dependencies.
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.
The first difference to note is the file extension used, AsciiDoc files must end with
Read up on the syntax then create a new post with Hugo by running
hugo new posts/post-name.adoc and start writing.
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” (
== Header title
notice the two equal signs, this is important.
Note that all types of front matter in Hugo are compatible with all supported content formats.
hugo new command uses YAML front matter formatting by default, but none of the other options (JSON, TOML, Org) will cause issues with AsciiDoc.