asciidoctor/asciidoctor-maven-plugin

A Maven plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.

Java

324

785 commits

updated Sep 7, 2026

asciidoctor.org

See the code

README

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:

汉语

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.2.0</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.2.0</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. New features and fixes will be added as minor/patch releases.

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.

Significant stargazers

Matt Sicker

134 followers · starred Apr 2018

xiejiashuai

5 followers · starred Oct 2021

Similar repos

asciidoctor/asciidoctor-gradle-plugin

A Gradle plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.

303

same org

asciidoctor/asciidoctorj

:coffee: Java bindings for Asciidoctor. Asciidoctor on the JVM!

672

same org

asciidoctor/asciidoctor

:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting…

5,218

same org

asciidoctor/kramdown-asciidoc

A kramdown extension for converting Markdown documents to AsciiDoc.

243

same org

apache/maven-javadoc-plugin

Apache Maven Javadoc Plugin

108

mojohaus/versions-maven-plugin

Manages the versions of artifacts in a project POM

367

ascopes/protobuf-maven-plugin

Protoc integration for Maven. Supports Protoc plugins (such as gRPC), building from descriptors,…

168

Kotlin/dokka

API documentation engine for Kotlin

3,810

Languages

Java

96.5%

Groovy

3.2%

asciidoctor/asciidoctor-maven-plugin

A Maven plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.

Java

324

785 commits

updated Sep 7, 2026

asciidoctor.org

See the code

README

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:

汉语

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.2.0</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.2.0</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. New features and fixes will be added as minor/patch releases.

Contributing

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.

Similar repos

asciidoctor/asciidoctor-gradle-plugin

A Gradle plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.

303

same org

asciidoctor/asciidoctorj

:coffee: Java bindings for Asciidoctor. Asciidoctor on the JVM!

672

same org

asciidoctor/asciidoctor

:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting…

5,218

same org

asciidoctor/kramdown-asciidoc

A kramdown extension for converting Markdown documents to AsciiDoc.

243

same org

apache/maven-javadoc-plugin

Apache Maven Javadoc Plugin

108

mojohaus/versions-maven-plugin

Manages the versions of artifacts in a project POM

367

ascopes/protobuf-maven-plugin

Protoc integration for Maven. Supports Protoc plugins (such as gRPC), building from descriptors,…

168

Kotlin/dokka

API documentation engine for Kotlin

3,810

Significant stargazers

Matt Sicker

134 followers · starred Apr 2018

xiejiashuai

5 followers · starred Oct 2021

Languages

Java

96.5%

Groovy

3.2%