Consensus on script to include asciidoc diagrams in hugo posts

I am still new to Hugo, so still trying to get a feel for everything. One challenge I ran into has to do with including diagrams in my posts. So I write my posts in Asciidoc, and there are some nice tools like asciidoctor-diagrams that allow me to include graphviz, mermaid, or planetuml diagrams in the final pdf or html pages.

It seems that Hugo does not currently support running asciidoctor-diagrams when calling the asciidoctor tool to compile posts. So various people have posted about scripts they developed to get around this limitation. I include a few examples of these scripts below. BUT, my question is really whether there is a consensus on the best way to do this now? I was not sure what the latest thinking or approach was. Each of these scripts do similar things but in slightly different ways. So I figured I would ask.

Once post had a script like this:

if [ -f /usr/local/bin/asciidoctor ]; then

$ad -v -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

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

Another post looked like this using safe mode:


ARGS=$(echo "$@" | sed -e 's/--safe//')

/usr/bin/asciidoctor_real -r asciidoctor-html5s -r asciidoctor-diagram -b html5s $ARGS

And there was also a pull request on this topic as well.

gohugo PR #7281

But I don’t really know which approaches work, is there any consensus around the best approach, etc.

@muenchhausen if you have any thoughts, please chime in since the pull request was created by you.

Since Hugo release 0.74.0, you do not need any hack on asciidoctor cli any longer. This should be obsolete (hopefully). You can configure all necessary extensions in Hugo config.toml excplicitly. You find this documented in Hugo external-helper-asciidoctor. Please make sure that workingFolderCurrent = true is set. A sample project in progress can be found here.

@muenchhausen Okay excellent. Yes, I am so glad that this is working now and I don’t need to mess around with the scripts. I ended up having to upgrade Hugo to the current version, but this started working after that. Thanks so much for your help.

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.