How to customise helper command? E.g. how to pass "-r asciidoctor-diagram" to asciidoctor?

Is there a way to customise the actual command line that corresponds to a given helper?

I need to use asciidoctor’s diagram extension, which is usually activated on the command line by running the asciidoctor command with the -r option like this:

$ asciidoctor -r asciidoctor-diagram sample.adoc

For more detail see

It would be great to have a way to specify a file extension (e.g. .adoc) and its corresponding helper command (e.g. asciidoctor -r asciidoctor-diagram) in the config.toml/yaml file.

For Asciidoc currently no.

As a real hack on unix you can place write a script /usr/local/bin/asciidoctor that add parameter:

if [ "${caller}" = "/usr/bin/hugo" ]
   /usr/bin/asciidoctor -r asciidoctor-diagram ${@} | sed -E -e "s/img src=\"([^/]+)\"/img src=\"\/\1\"/"
   #  move out all images
  cp -p *.png images/ 
   exec /usr/bin/asciidoctor -r asciidoctor-diagram ${@}

This fixes also issues with included images as hugo calls asciidoctor in root and not in the real workdir.
asciidoctor-diagram places all png files in actual working dir.

May be we can form a feature request, so documents can processed with hugo and asciidoctor without changes.

1 Like

Good workaround, thanks!

To get the correct image path I had to tweak the imagedir:

:imagesdir: …/…/images

Is there a better solution?

Here’s how I deal with images and Asciidoctor: Every post is a leaf bundle and any image that I use in only one post is located in that post’s bundle directory and referenced like this in the post’s index.adoc:

image::./foo.png[alt text]

If you do not set the imagesdir attribute, the above will work.

For any image bar.png that is used in multiple posts, I put it in site-root/static/images and reference it like this:

image::{staticimagesdir}/bar.png[alt text]

I set the staticimagesdir attribute (and other attributes) in a file that I include in all my index.adoc files. Here’s the setting I use:

:staticimagesdir: /images

The reason I name it staticimagesdir is so I will remember that it is in my Hugo site root’s static directory.

I’d love to hear how other people use AsciiDoc with Hugo. I :heart: AsciiDoc, but it has been a challenge to figure out a sane way to use images and includes with Hugo bundles. Some day I will write about AsciiDoc includes, AsciiDoc jails, and Hugo :scream:


I am currently preparing a pull request that should solve the image rendering problem. This pull request adds --base-dir and outdir=, so hopefully @joerg1 s patch wont be necessary any longer soon. Just have a look to the current discussion here: