The Asciidoctor Maven Plugin is the official way to convert yourAsciiDoc documentation usingAsciidoctor from anApache Maven build.

The conversion can happen in 2 flavors:

1. as a Maven plugin: AsciiDoc files are converted at full Asciidoctor power independently from Maven site,

2. as a Maven site integration: AsciiDoc files are integrated with Maven reports, which comes witha few limitations (see below for details).

Full documentations is available in theUSER MANUAL, if you have questions, please drop them at thePROJECT CHAT.

• 汉语

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

1. Place your AsciiDoc sources insrc/docs/asciidoc.

2. Add the minimal configuration to yourpom.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>

3. Run the plugin’s associated phase.

   $ mvn generate-resources

If you want to generate your Maven site with Asciidoctor

1. Place your AsciiDoc sources insrc/site/asciidoc.

2. Add the minimal configuration to yourpom.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>

3. Run the plugin’s associated phase.

   $ mvn site:site

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

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.

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

TheContributor Guide will help you start with the code.

Copyright © 2013-2024 Jason Porter, Dan Allen, Abel Salgado Romero and the individual contributors.Use of this software is granted under the terms of the Apache License, Version 2.0.

See theLICENSE for the full license text.