asciidoctor / asciidoctor-maven-plugin

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

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:

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 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.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.

1. Place your AsciiDoc sources in src/docs/asciidoc.

2. Add the minimal configuration to your pom.xml.

   <plugin>
       <groupId>org.asciidoctor</groupId>
       <artifactId>asciidoctor-maven-plugin</artifactId>
       <version>3.0.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 in src/site/asciidoc.

2. 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.12.1</version>
               <dependencies>
                   <dependency>
                       <groupId>org.asciidoctor</groupId>
                       <artifactId>asciidoctor-parser-doxia-module</artifactId>
                       <version>3.0.0</version>
                   </dependency>
               </dependencies>
           </plugin>
       </plugins>
   </build>

3. 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

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 the LICENSE for the full license text.

asciidoctor-maven-plugin's Issues

Add missing parameter for eruby option

Currently, the option to specify the eruby implementation is missing. The name of this parameter should be eruby. The default value should be unset (or erb). It's not necessary to limit the possible values, though the two values supported by the Java integration out of the box are erb and erubis.

Update to asciidoctor 0.1.1

Skip files and directories that begin with underscore

Don't process files or directories that begin with underscore. By doing so, we honor the naming convention of document fragments (includes), which should not be processed as top-level documents.

sourceDocumentName should be relative to sourceDirectory

The configuration variable sourceDocumentName implies that it is a file name, not a full path. Thus, I would expect it to be resolved relative to the sourceDirectory setting. Instead, it is treated as a full path.

It might also be nice to allow the extension to be left off and automatically look for files ending in .ad, .adoc and .asciidoc.

Here's what I expect to be able to use in the configuration of the plugin:

<configuration>
  <sourceDirectory>docs</sourceDirectory>
  <sourceDocumentName>golo-guide</sourceDocumentName>
</configuration>

The main purpose of the sourceDocumentName configuration setting is to single out the master file to process out of a directory of AsciiDoc source files.

zip goal

It is common to generate the doc then zip it (if html or not single file as for the pdf case) and finally attach it to the build.

It is doable through other plugins but a pain so adding the zip goal to do it easily:

mvn asciidoctor:zip

The goal accepts a classifier for the produced zip, the zip destination, a boolean to ask to not attach or to attach (and same to zip or not, but if zip = false, attach is ignored) as configuration.

PS: PR in the http goal issue

Support asciidoctor-fopdf out of the box to generate PDF

Alongside HTML generation, also generate a PDF with asciidoctor-fopdf.

https://github.com/mojavelinux/asciidoctor-fopdf

templateDir not respected with 0.1.3 release

Asciidoctor.css missing

Hi,

I'm almost sure it's a silly question, but when I trigger a html doc generation, the output is raw, I mean no style.
This is an extract of the pom.xml

<configuration>
  <backend>html5</backend>
  <attributes>
    <linkcss>true</linkcss>
    <toc2>true</toc2>
  </attributes>
</configuration>

The page is looking for ```.
Shouldn't, this CSS, be automatically provided or should I place it explicitly in the project?

Thank you.

Registering custom extensions

What is the status about supporting "built-in" or custom filters in this maven plugin?
Is it feasible currenlty or is it only on asciidoctorJ roadmap ?

toc2 attribute does not work

I have a project using maven asciidoctor plugin and the toc2 attribute does not work:

<attributes>
   <toc2/>
   ...
</attributes>

linkcss attribute value is ignored

With version 0.1.4.
When setting linkcss attribute to false in the attributes tag for an html output, the value is interpreted always as true.
After some testing it seems that when the attribute is set is it taken as true no matter its value (ignoring also embeddedAssets parameter), when linkcss is just not set (removed or commented) it is interpreted as false and CSS are embedded into the html output.

If this is the normal behauviour, the example in https://github.com/asciidoctor/asciidoctor-maven-plugin should be changed.
Also the use of linkcss with embeddedAssets is quite confusing, I undertand from this #91, that embeddedAssets should overwrite linkcss in some way and not the other way arround as it is now.

Outdated build instructions

Please make sure that the build instructions are up to date.

OutputDirectory problem on Windows

When running on windows, I receive the following issue

Caused by: org.jruby.exceptions.RaiseException: (IOError) target directory does not exist: C:/opensource/StatelessPrime/angularJS/AngularPrime/trunk/C:/opensource/StatelessPrime/angularJS/AngularPrime/trunk/C:/opensource/StatelessPrime/angularJS/AngularPrime/trunk/target/generated-docs
at RUBY.render(jar:file:c:/maven_repository/org/asciidoctor/asciidoctor-java-integration/0.1.2/asciidoctor-java-integration-0.1.2.jar!/gems/asciidoctor-0.1.2/lib/asciidoctor.rb:811)

So it seems that path passed to JRuby script is expected to be relative to current directory but full path is supplied.

embedAssets=true gives a broken image if the image is added in an included adoc

My structure:

training.adoc // includes lab101/lab101.adoc
lab101/lab101.adoc // shows images/myImage.png
images/myImage.png

With embedAssets=true, the image is a broken image.

add some hints for contributors

How ruby is setup, the mojo which simply delegates to a ruby script which calls asciidoctor.... can be interesting info which could be in README or another page

synchronizations in AsciidoctorMojo doesn't have @Parameter so it is not usable

Asciidoctor Maven Plugin broken

I am trying to integrate the asciidoctor-maven-plugin into my build process, but it seems like the plugin is broken. I am using the current master version. The error is:

SyntaxError: <script>:6: syntax error, unexpected ','

    Asciidoctor.render_file({path, :in_place => true, :safe => Asciidoctor::SafeMode::UNSAFE, :base_dir => $srcDir, :backend => $backend})

I never looked into Ruby before and I do not understand what is going on here. Since with a rollback to revision 2861f84 works, I assume that it has to do with the asciidoctor 0.1.0 version.

Document in README how to propagate pom model properties to the document.

Document in the README how to propagate pom model properties, such as the version, to the AsciiDoc document using custom attribute assignments.

Refer to the following post for details:

http://discuss.asciidoctor.org/Maven-plugin-a-way-to-incorporate-a-maven-property-in-asciidoc-td992.html

Add a sourceDocumentName option

Add the option sourceDocumentName to specify a single AsciiDoc file to render. This option covers the use case where you have a bunch of chapter files and a single master file that includes the chapter files. It's unnecessary to run Asciidoctor on all the AsciiDoc files in the directory.

The name of this option mimics the jdocbook plugin.

<configuration>
  <sourceDirectory>docs</sourceDirectory>
  <sourceDocumentName>master.adoc</sourceDocumentName>
</configuration>

Document in README how to set and unset boolean attributes

Document in the README how to set and unset boolean attributes which control features such as numbered, toc and the like. The Asciidoctor Java API accepts the value true to set an attribute and the value false to unset an attribute. Thus, the documentation should explain how to work with boolean attribute values.

This documentation should resolve #62.

Change Java package to org.asciidoctor

To be consistent with the groupId and with the other projects in the Asciidoctor ecosystem, the Java package should be org.asciidoctor rather than org.asciidoc.

Allow the baseDir to be specified

Allow the baseDir to be specified. Set the default value to the project root to be consistent with the Gradle plugin.

Due to the fact that Maven does not recognize empty values, use the placeholder value "null" to indicate that the value of baseDir should be left unset.

Add new attributes from 0.1.4

The attributes 'attribute-missing' and 'attribute-undefined' should be supported.

the configuration option "imagesDir" is ignored. But "imagesdir" (with a lowercase "D") is taken into consideration

The option "imagesDir" as described in documentation is not taken into consideration by the plugin.

Option TemplateDir appears twice in README file

The templateDir option appears twice in the README file

templateDir
disabled by default

templateDir
defaults to null

Should be the first option and not null ?

Allow properties with empty string and false values to be specified

Empty string and false are important attribute values in Asciidoctor. For example, to enable the table of contents, you set the toc attribute to empty string. To embed css, you set the linkcss attribute to nil or false.

Currently, the Maven plugin doesn't properly handle either of these attribute values.

The problem with empty string traces back to a shortcoming in Maven. If the value of a property is empty, Maven treats that as null. These null values need to be converted back to empty string before passing them on to the Asciidoctor Java integration.

A value of false is not being interpreted correctly because the attributes map is configured to only accept string values. It needs accommodate boolean values as well. Therefore, the map entries should be of type <String, Object>.

Once those two changes are map, the following post-processing needs to be added:

for (String key : attributes.keySet()) {
    if (attributes.get(key) == null) {
        attributes.put(key, "");
    }
}

In Asciidoctor, a value of null and false is equivalent, so we can assume null is empty string and require the use of false to disable an attribute.

With these changes in place, the following configuration is possible:

<attributes>
    <toc/>
    <idprefix/>
    <linkcss>false</linkcss>
</attributes>

That's the equivalent of the following Ruby code:

:attributes => {'toc' => '', 'idprefix' => '', 'linkcss' => false}

(Technically, the toc attribute could be set to true and it would still work the same).

log processed files

The following patch works but it would be better if the java integration was returning the info:

Index: src/main/java/org/asciidoc/maven/AsciidoctorMojo.java
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
--- src/main/java/org/asciidoc/maven/AsciidoctorMojo.java   (revision 0178fe0977c9f3fd8b1af7de0640eb8a93c3edf4)
+++ src/main/java/org/asciidoc/maven/AsciidoctorMojo.java   (revision )
@@ -12,20 +12,22 @@

 package org.asciidoc.maven;

-import java.io.File;
-import java.util.HashMap;
-import java.util.Map;
-
 import org.apache.maven.plugin.AbstractMojo;
 import org.apache.maven.plugin.MojoExecutionException;
 import org.apache.maven.plugin.MojoFailureException;
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.Parameter;
+import org.asciidoctor.AsciiDocDirectoryWalker;
 import org.asciidoctor.Asciidoctor;
 import org.asciidoctor.AttributesBuilder;
 import org.asciidoctor.OptionsBuilder;
 import org.asciidoctor.SafeMode;

+import java.io.File;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
 /**
  * Basic maven plugin to render asciidoc files using asciidoctor, a ruby port.
  *
@@ -91,8 +93,15 @@

         if (sourceDocumentName == null) {
             asciidoctorInstance.renderDirectory(sourceDirectory, optionsBuilder.asMap());
+
+            // TODO: should be get from java integration and not redo here
+            final List<File> asciidoctorFiles = new     AsciiDocDirectoryWalker(sourceDirectory.getAbsolutePath()).scan();
+            for (final File s : asciidoctorFiles) {
+                getLog().info("Rended " + s.getAbsolutePath());
+            }
         } else {
             asciidoctorInstance.renderFile(sourceDocumentName, optionsBuilder.asMap());
+            getLog().info("Rended " + sourceDocumentName);
         }

     }

Create documentation for the plugin

We need to document how to use it and how to configure it. Also we should mention which files it looks for.

none of the code highlighters work

Are they supposed to?

java 7

Hi

Could the plugin be java7 only or have features for java 7 only or should it be backported in j6?

I think to new file watch api

provide a simple boolean to activate embedding of css/js/img

When generating html (slide or doc) it would be great to be able to embed the js, css and pictures (base 64) through a single param and not with multiple ones (thta's very useful for slides).

Side note: would be great to support it in templates too (deckjs for instance), so maybe a quick parsing replace after generation can be mandatory.

Default value for headerFooter parameter should be true

To be consistent w/ the Gradle plugin, the headerFooter parameter should default to true. This is also a reasonable default since most users will be using the plugin to process full AsciiDoc files. It also means they won't have to mess w/ the configuration by default.

The reason the header footer is disabled in the Ruby API by default is because the common use case for the API within Ruby is to render an embedded document.

Generate asciidoctor command line

That should be interesting to generate the asciidoctor command used by maven plugin so we can, in case of trouble, copy/paste the command and compare with asciidoctor running in command line if there are differences

Create a branch or profile for testing AsciidoctorJ snapshots

I think the Maven plugin should have a separate branch setup to build against an AsciidoctorJ snapshot. An alternative is to add a profile in the POM on the master branch for building against the AsciidoctorJ snapshot. Either way works for me.

asciidoctorJ-diagrams extension

As plantuml and ditaa are JAR available on maven,
do you have your own plan to have an asciidoctorj-diagrams extensions on the java side similar to the existing asciidoctor-diagrams ?

Create an integration project

My hope is to have this be part of this project, maybe we can have it be this project. We need some way of testing the plugin within an actual working maven project. This will also help us find perf issues and other integration bugs.

Include seems broken with version 0.1.4-SNAPSHOT

I was used to have a main parent page which includes a set of children pages.
E.g:

include::basics.asciidoc[]

Since version 0.1.4-SNAPHOT, the children pages are properly generated but not merged into the parent page.

prefix properties

Hi,

shouldn't @parameter(property) be prefixed by "asciidoctor" to use -Dasciidoctor.xxx instead of xxx directly? could generate conflicts otherwise

Resources (styles, javascripts) are not copied

Hi,

I have created a maven project using asciidoctor maven plugin but also maven copy resources but when mvn install or mvn package are executed no files are copied into generated directory. Find in attachment a small project

Liunk : https://www.dropbox.com/s/8kay656oxp168i3/mydoc.zip

cheers,

Charles

Allow to generate directly PDF

Generating pdf is possible through docboock then another plugin usage, would be great to make it trivial simplifying the chaining (probably) or using an existing pdf library

Note: this was first discussed in the issue #27

Create a change log

We need to have a change log, probably on the wiki, though I'm open to other areas.

maven-site-plugin does not appear to work

See asciidoctor/asciidoctor#494

Create initial release for Sonatype OSS

Out of the box support for theme

Hello, sorry for the newbie question, but when trying to use the theme attribute, nothing happens. is it not supported currently by the plugin

<attributes>
      <theme>volnitsky</theme>
 </attributes>

Thanks

The imagesDir option is not propagated to Asciidoct vai the Asciidoctor-java-integration call.

Generate for multiple backends in a single execution

Like the Maven jDocBook plugin, the Asciidoctor Maven plugin should be able to output using multiple backends in a single execution.

I think this is just a matter of having a nested configuration for each backend, where the parent configuration is the shared and the nested configuration contains any attributes specific to that backend. This arrangement of configuration allows the target filename to be tuned per backend.

In the jDocBook plugin, this nested configuration is named formats. I think the term backends applies here best.

See https://github.com/pressgang/pressgang-tools/blob/master/pressgang-tools-example/pom.xml for an example of how the configuration looks in the jDocBook plugin when using multiple formats.

Setup some sort of CI

Could be a cloudbees instance and / or TravisCI

Update to asciidoctor-java-integration 0.1.3

Create an AsciidoctorWarMojo to generate a war file with rendered documentation

I have seen that in Asciidoctor-Maven-Plugin you can render the AsciiDoc files to the required output (let's say html5) and then zip it or for example make them available as an http resource using Netty.

But I think could be also useful to generate a war file ready to be deployed in an application server like Tomee, JBoss, ... using for example Cargo plugin or any Jenkins plugin.

I am thinking about a scenario that happens in my case. We are using a farm of jenkins to generate our software versions which if compiles, all tests passes, ... they are deployed into a test environment. But if we were using AsciiDoc and Maven plugin to render all the documentation, all these documentation would be generated into a directory which on next build job would be removed, so it would not be available to external departments. One solution could be generating a zip file and copy it to a shared directory, but also if a war was generated then we could automatically deploy it to a documentation server.

Error reported during maven build phase

Hi,

When I run asciidoctor maven plugin within IDEA IntelliJ, I get this error which is not reported when executed as a command line in a Terminal

https://gist.github.com/7565838

Charles