plantUML with Asciidoctor-pdf

The last few days I had to learn the hard way that plantUML (as part of asciidoctor-diagram) is not a frient of asciidoctor-pdf.

I always thought that having plantUML for HTML rendering up and running with asciidoctor also means that the PDF backend would be running fine.

Unfortunately, asciidoctor-pdf is looking in the source-folder for the generated plantUML images and can’t find them there.

I didn’t quite get the whole picture - which module is picking up the images from where or generates them in which folder, but I got the impression that the problem is quite complex. Dan Allen pointed me to some comments which describe solutions (the Asciidoctor community is really great), but while I was trying to find a solution which fits my case, I got the feeling that I will get standard images or plantUML up and running, but not both.

I’ve now got a solution which I think is quite ok:

First, I splitted the generation of HTML and PDF into two seperate tasks:

tasks.withType(AsciidoctorTask) { docTask ->
    outputDir = file(targetDir)
    sourceDir = file(srcDir)

        'pdf-stylesdir': 'pdfTheme',
            'pdf-style': 'custom',
            'source-highlighter': 'coderay',
            'imagesdir': 'images',
            'toc': 'left',
            'icons': 'font',
            'javaVersion'         : "$javaVersion",
            'currentDate'         : "$currentDate",
            'allow-uri-read'      : true
    // ...

    // configure source and output files and folders
    sourceDir = file('src/docs')
    sources {
        include 'arc42-venom.adoc'
        include 'index-orga.adoc'
    outputDir = file('build/docs')
    // good to see what the build is doing...
    logDocuments = true

    requires = ['asciidoctor-diagram']

task generateHTML (
        type: AsciidoctorTask,
        description: 'use html5 as asciidoc backend') {
    attributes \
            'plantUMLDir'         : ''
    backends = ['html5']

task generatePDF (
        type: AsciidoctorTask,
        description: 'use html5 as asciidoc backend') {
    attributes \
            'plantUMLDir'         : file('build/docs/images/plantUML/').path
    backends = ['pdf']

Second (already included in the source above), I added an attribute plantUMLDir which specifies the absolute path to a folder where I want to have my plantUML images generated to.

So, my trick now is to use this absolute path in my plantUML diagram definitions

!pragma graphviz_dot jdot

and this seems to work :-)

  • for HTML, plantUML images are referenced relative to the document
  • for PDF, plantUML images are are referenced absolute, but since they are stored within the pdf, this does not matter
  • images are rendered ok in HTML and PDF
  • plantUML is rendered ok in HTML and PDF
  • plantUML files are created in build-folder
First appeared May 1, 2017 on