Hugo & Asciidoctor cheat sheet

This site is mainly created by Asciidoctor and Hugo. See here how to get things running.

1. How to install Asciidoctor

This installs Asciidoctor plus its diagram extension.

1.1. Debian

apt install asciidoctor
gem install asciidoctor-html5s
gem install asciidoctor-diagram
apt install default-jdk
apt-get install graphviz

1.2. Mac OS X

brew install asciidoctor
gem install asciidoctor-html5s
gem install asciidoctor-diagram
brew install graphviz

1.3. Windows

Install the Graphviz MSI from https://graphviz.gitlab.io/_pages/Download/Download_windows.html.
Add the path to dot.exe (e. g. C:\Program Files (x86)\Graphviz2.38\bin) to the Windows system path.
In case you don’t have Ruby, install the recommended Ruby version from here: https://rubyinstaller.org/downloads.

Open a terminal and type

gem install asciidoctor
gem install asciidoctor-html5s
gem install asciidoctor-diagram

2. How to install Hugo

These methods ensure to install the latest hugo version.

2.1. Debian

Find the latest version on https://github.com/gohugoio/hugo/releases. Choose the one that is tagged extended and has extension _Linux-64bit.deb. For version 0.55.6, the installation is done as follows:

wget https://github.com/gohugoio/hugo/releases/download/v0.55.6/hugo_extended_0.55.6_Linux-64bit.deb
sudo dpkg -i hugo*.deb

2.2. Mac OS X

git clone https://github.com/gohugoio/hugo.git
cd hugo
brew install go
go install --tags extended

2.3. Windows

In case you don’t have Chocolatey, install it using an administrative cmd.exe (details see here):

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

You can install hugo via choco with the following one-liner, using an administrative cmd.exe:

choco install hugo-extended -confirm

3. How to make Hugo use Asciidoctor with extensions

This workaround is only possible for Linux and Mac, not for Windows. Place a file asciidoctor in the root of your hugo project with the following content:

asciidoctor

#!/bin/bash
if [ -f /usr/local/bin/asciidoctor ]; then
  ad="/usr/local/bin/asciidoctor"
else
  ad="/usr/bin/asciidoctor"
fi

$ad -B . -r asciidoctor-diagram -a icons=font -a docinfo=shared -a nofooter -a sectanchors -a experimental=true -a figure-caption! -a source-highlighter=highlightjs -a toc-title! -a stem=mathjax - | sed -E -e "s/img src=\"([^/]+)\"/img src=\"\/diagram\/\1\"/"

mkdir -p static/diagram

if ls *.svg >/dev/null 2>&1; then
  mv -f *.svg static/diagram
fi

if ls *.png >/dev/null 2>&1; then
  mv -f *.png static/diagram
fi

Make it executable (chmod +x asciidoctor).

Hugo will call this script instead of the installed asciidoctor. It is exactly the one that is used to create this web site. The sed command replaces asciidoctor-diagram links so they point to folder static/diagram. The mv commands move the images that are created by asciidoctor-diagram into folder static/diagram.

To make Hugo call this script instead of the installed asciidoctor, it is required to add the hugo project root folder to the path. This script does this and then starts the Hugo server. Again, it is exactly the script that runs this web site, because the following code block is created from the git repo:

run_production_server.sh

PATH=$PWD:$PATH /usr/local/bin/hugo server --disableFastRender --disableLiveReload --renderToDisk --baseURL https://zipproth.com/ --appendPort=false --environment production