Installing Asciidoctor

Markdown is super simple and therefore limited. Asciidoc is much more capable. In Hugo, the Asciidoc files are converted to HTML using the asciidoctor.org toolchain.

Review the Asciidoc User Manual for demonstration of the capabilities.

#1 Install Ruby Interpreter

Asciidoctor requires Ruby Laguage support, to install Ruby:

Mac OS: $ brew install ruby
Ubuntu: $ sudo snap install ruby

For other systems follow directions on ruby-lang.org/en/documentation/installation website.

Check the Ruby version:

$ ruby --version
ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux]

Be sure that Ruby version is above 2.0.0

#2 Install Asciidoctor Gem

Ruby packages are called gems, to install Asciidoctor gem:

$ gem install asciidoctor
Fetching asciidoctor-2.0.12.gem
Successfully installed asciidoctor-2.0.12
Parsing documentation for asciidoctor-2.0.12
Installing ri documentation for asciidoctor-2.0.12
Done installing documentation for asciidoctor after 1 seconds
1 gem installed

Check installation:

$ asciidoctor --version
Asciidoctor 2.0.12 [https://asciidoctor.org]
Runtime Environment (ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

if the asciidoctor command is not found, the path is probably missing.add the path:

[I] /home/sporty/hugo/mysite~> gem environment
RubyGems Environment:
  - RUBYGEMS VERSION: 3.1.4
  - RUBY VERSION: 2.7.2 (2020-10-01 patchlevel 137) [x86_64-linux]
  - INSTALLATION DIRECTORY: /home/sporty/.gem
  - USER INSTALLATION DIRECTORY: /home/sporty/.gem/ruby/2.7.0
  - RUBY EXECUTABLE: /snap/bin/ruby
  - GIT EXECUTABLE: /usr/bin/git
  - EXECUTABLE DIRECTORY: /home/sporty/.gem/bin
  - SPEC CACHE DIRECTORY: /home/sporty/.gem/specs
  - SYSTEM CONFIGURATION DIRECTORY: //etc
  - RUBYGEMS PLATFORMS:
    - ruby
    - x86_64-linux
  - GEM PATHS:
     - /home/sporty/.gem (1)
     - /snap/ruby/189/lib/ruby/gems/2.7.0
  - GEM CONFIGURATION:
     - :update_sources => true
     - :verbose => true
     - :backtrace => false
     - :bulk_threshold => 1000
  - REMOTE SOURCES:
     - https://rubygems.org/

1	Gem installation directory.

Find the GEM PATHS: and look for folder under you home folder.

View the Gem folder

$ cd /home/sporty/.gem
$ ls
 bin   build_info   cache   doc   extensions   gems   ruby   specifications   specs

Notice there is a bin folder,

$ cd bin
$ ls
 asciidoctor

The asciidoctor executable folder can be added to shell paths or a symbolic link to the executable can be created. To create the symbolic link:

$ ln -s  ~/.gem/bin/asciidoctor ~/.local/bin/asciidoctor

Verify that Asciidoctor works:

$ asciidoctor --version
Asciidoctor 2.0.12 [https://asciidoctor.org]
Runtime Environment (ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

#3 Add Asciidoctor template

Offcial Hugo archetypes documentation.

Create new file named default.adoc in the archetypes folder, your tree should look like this:

├── archetypes
│   ├── default.adoc (1)
│   └── default.md
├── config.toml
├── content
│   ├── _index.md
│   ├── about-me.md
│   └── blog
│       └── index.md
├── data
├── layouts
├── public
├── resources
├── static
└── themes

1	The New asciidoctor template.

Edit the default.adoc file and add something similar to below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15 ---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true

categories:
    - "category1"
tags:
    - "tag1"
    - "tag2"
---

= {{ replace .Name "-" " " | title }}
{{ .Site.Author.name }} {{ with .Site.Author.email }}<{{ . }}>{{ end }}
{{ dateFormat "2006-01-02" .Date }}

New ascidoctor page can be created by:

$ hugo new hello-asciidoc.adoc

Edit the newly created asciidoc file and add some content.

You should now be able to preview this page like any other markdown document.

← Deploy on Vercel | Index | Configure Asciidoctor →