AsciiDoc and UML are two well known technologies for software design. A very nice way of creating beautiful PDF documents is to combine both by embedding PlantUML in your AsciiDoc. Generating the PDF can be a bit cumbersome, but with the following Maven setup it is quick and easy.

This blog describes a simple example setup of an AsciiDoc document with embedded PlantUML in it. You can use this as a template for your own document.

First we create a Maven project with an AsciiDoc file in src/main/asciidoc:

= PlantUML in AsciiDoc
:doctype: article
:toc: left
:toclevels: 4
:sectnums:
:source-highlighter: rouge
:imagesdir: ./images

== Intro

This is an example https://docs.asciidoctor.org[AsciiDoc] document which contains a few simple
https://plantuml.com/class-diagram[PlantUML] diagrams.

<<<
== Examples

=== Sequence diagram

Example of a simple Sequence diagram.

.Sequence diagram
[plantuml, sequence-diagram, png]
----
Alice -> Bob: request
Bob --> Alice: response
----

=== Class diagram

Example of a simple Class diagram.

.Class diagram
[plantuml, class-diagram, png]
----
class Class01 {
  - privateField
  # protectedField
  ~ packagePrivateField
  + publicField
  + publicMethod()
}

Class01 "1" *-- "0..n" Class02 : contains

Class03 o-- Class04 : aggregation

Class05 --> "1" Class06
----

<<<
=== Component diagram

Example of a simple Component diagram.

.Component diagram
[plantuml, collaboration-diagram, png]
----
actor CustomerSupport as sup
component CustomerPortal as por
component CustomerService as ser
database CustomerDb as db

sup --> por : 1 maintain customer data
por --> ser : 1.1 maintain customer data request
ser --> db : 1.1.1 persist customer data
----

With the AsciiDoc plugin you can view the rendered output directly in your IntelliJ IDEA.

And we use the following pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.jdriven</groupId>
    <artifactId>plantuml-asciidoc-example</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <asciidoctor-maven-plugin.version>3.2.0</asciidoctor-maven-plugin.version>
        <asciidoctorj-pdf.version>2.3.19</asciidoctorj-pdf.version>
        <asciidoctorj-diagram.version>3.0.1</asciidoctorj-diagram.version>
        <asciidoctorj-diagram-plantuml>1.2025.3</asciidoctorj-diagram-plantuml>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>${asciidoctor-maven-plugin.version}</version>

                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>${asciidoctorj-pdf.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-diagram</artifactId>
                        <version>${asciidoctorj-diagram.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-diagram-plantuml</artifactId>
                        <version>${asciidoctorj-diagram-plantuml}</version>
                    </dependency>
                </dependencies>

                <configuration>
                    <sourceDirectory>src/main/asciidoc</sourceDirectory>
                    <backend>pdf</backend>
                    <requires>
                        <require>asciidoctor-diagram</require>
                    </requires>
                </configuration>

                <executions>
                    <execution>
                        <id>generate-pdf-documents</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Next we run ./mvnw clean package and we can view the generated PDF file in target/generated-docs/plantuml-in-asciidoc-example.pdf.

It should look like this.

Here you can find the sources.

shadow-left