Enable AsciiDoc

To utilize AsciiDoc markup in a Hugo site, some extra configuration is required — both on your local machine and in your deployment solution (Netlify, AWS Amplify, a container image).

Once set up, you will be able to use the ascii shortcode and/or create your own.

Before you start

How to enable AsciiDoc markup

The following steps have been tested with Netlify. By providing a Gemfile at the root level, Netlify knows to automatically install both Ruby and the required gems listed in the Gemfile. This may not be the case in your deployment solution.

Install

  1. Install Ruby. 
    brew install rbenv ruby-build
  2. Install asciidoctor. 
    brew install asciidoctor
  3. Create a Gemfile at the root of your Hugo project and add the following: 
    source 'https://rubygems.org'
gem 'asciidoctor'
  4. Open your Hugo security configuration (e.g. config/_default/security.yaml).
  5. Update security.exec:
    • We need to whitelist the ascii processor tool, asciidoctor.
    • We need to whitelist the GEM_PATH.
    exec:
  allow:
    - '^dart-sass-embedded$'
    - '^go$'
    - '^npx$'
    - '^postcss$'
    - '^rst2html.py$'
    - '^rst2html$'
    - '^asciidoctor$'
  osEnv: 
    - (?i)^(PATH|PATHEXT|APPDATA|TMP|TEMP|TERM|HOME|GEM_PATH)$

Configure

You can use basic AsciiDoc markup without any additional configuration. However, you can customize and extend the support by adding extensions and updating the optional attributes.

  1. Open your Hugo markup configuration (e.g. config/_default/markup.yaml).
  2. Add the following attributes: 
      asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: true
  3. Update the list of extensions you’d like to support.

Troubleshooting

It’s possible that whitelisting GEM_PATH does not work for you. In that case, try to whitelist GEM_HOME or RVM_*. See this related Github issue for historical context.

Enable RST