Asciidoctor Maven Tools (Plugin & Site Integration)

The Asciidoctor Maven Plugin is the official way to convert your AsciiDoc documentation using Asciidoctor from an Apache Maven build.

The conversion can happen in 2 flavors:

as a Maven plugin: AsciiDoc files are converted at full Asciidoctor power independently from Maven site,
as a Maven site integration: AsciiDoc files are integrated with Maven reports, which comes with a few limitations (see below for details).

Full documentations is available in the USER MANUAL, if you have questions, please drop them at the PROJECT CHAT.

Translations of the document are available in the following languages:

汉语

📎	You’re viewing the documentation for the upcoming release. If you’re looking for the documentation for a stable release, please refer to one of the following tags: + 3.1.0 ⁃ 3.0.0 ⁃ 2.2.6 ⁃

Quickstart
Examples
Supported version
Contributing
Copyright and License

Quickstart

These are the minimal steps to convert your AsciiDoc documents to HTML with the asciidoctor-maven-plugin.

Place your AsciiDoc sources in src/docs/asciidoc.

Add the minimal configuration to your pom.xml.

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.1.1</version>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Run the plugin’s associated phase.
```
$ mvn generate-resources
```

If you want to generate your Maven site with Asciidoctor

Place your AsciiDoc sources in src/site/asciidoc.

Add the minimal configuration to your pom.xml.

Maven site integration

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.21.0</version>
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-parser-doxia-module</artifactId>
                    <version>3.1.1</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

Run the plugin’s associated phase.
```
$ mvn site:site
```

Examples

You can find examples ready to copy-paste in the Asciidoctor Maven examples project.

Supported version

asciidoctor-maven-plugin comes in two versions with support for Maven 3.8.8+ and 3.9.x versions.

Version 3.x.x: current development branch. This is the recommended version, new features and fixes will be added as minor/patch releases.
Version 2.2.x: maintenance branch. Fixes will be released as patch versions up until 31st January 2025.

Contributing

This plugin is an open source project made possible with the help of users and enthusiasts. To continue to be useful and to evolve, this plugin needs continuing contributions. There are multiple ways where you can help:

join the discussions
give feedback on ideas
report issue
test new releases
contribute source code to fix issues or add new functionality
write documentation

The Contributor Guide will help you start with the code.

Copyright and License

See the LICENSE for the full license text.