process-asciidoc: Converting documents

path where source files are located. By default checks for ${basedir}/src/docs/asciidoc, ${basedir}/src/asciidoc or ${basedir}/src/main/asciidoc in that order. When a custom value is set, no other paths are checked.

an override to process a single source file; defaults to all files in ${sourceDirectory}.

(named extensions in v1.5.3 and below) a List<String> of non-standard file extensions to convert. Currently, ad, adoc, and asciidoc will be converted by default

list of resource files to copy to the output directory (e.g., images, css). The configuration follows the same patterns as the maven-resources-plugin. If not set, all resources inside ${sourceDirectory} are copied.

<resources>
    <resource>
        <!-- (Mandatory) Directory to copy from. Paths are relative to maven's ${baseDir} -->
        <directory>DIRECTORY</directory>
        <!-- (Optional) Directory to copy to. By default uses the option `outputDirectory` -->
        <targetPath>OUTPUT_DIR</targetPath>
        <!-- (Optional) NOTE: SVN, GIT and other version control files are excluded by default, there's no need to add them -->
        <excludes>
            <exclude>**/.txt</exclude>
        </excludes>
        <!-- (Optional) If not set, includes all files but default exceptions mentioned -->
        <includes>
            <include>**/*.jpg</include>
            <include>**/*.gif</include>
        </includes>
    </resource>
    ...
</resources>

locations where converted sources and copied resources will be places. Note that relative paths are added to the project root path. Defaults to ${project.build.directory}/generated-docs.

defaults to null, used to override the name of the generated output file, can be a relative or absolute path. Useful for backends that create a single file, e.g. the pdf backend. All output will be redirected to the same file, the same way as the -o, --out-file=OUT_FILE option from the asciidoctor CLI command.

(not Maven’s basedir) enables to set the root path for resources (e.g. included files), defaults to ${sourceDirectory}

set this to true to bypass generation, defaults to false

enables to specify whether the documents should be converted in the same folder structure as in the source directory or not, defaults to false. When true, instead of generating all output in a single folder, output files are generated in the same structure. See the following example

    ├── docs                          ├── docs
    │   ├── examples.adoc             │   ├── examples.html
    │   └── examples            =>    │   └── examples
    │       ├── html.adoc             │       ├── html.html
    │       └── docbook.adoc          │       └── docbook.html
    └── index.adoc                    └── index.html

only used when baseDir is not set, enables to specify that each AsciiDoc file must search for its resources in the same folder (for example, included files). Internally, for each AsciiDoc source, sets baseDir to the same path as the source file. Defaults to false

defaults to html5

defaults to null (which trigger’s Asciidoctor’s default of article)

defaults to erb, the version used in JRuby

add frame around that content (i.e., the header and footer in HTML), defaults to true

list of directories of compatible templates to be used instead of the default built-in templates, empty by default.

template engine to use for the custom converter templates, disabled by default (null)

enables the built-in cache used by the template converter when reading the source of template files. Only relevant if the :template_dirs option is specified, defaults to true.

adds file and line number information to each parsed block (lineno and source_location attributes), defaults to false

tells the parser to capture images and links in the reference table available via the references property on the document AST object (experimental), defaults to false

a Map<String,Object> of Asciidoctor attributes to pass for conversion, defaults to null. Refer to the catalog of document attributes in the Asciidoctor user manual for a complete list.

<attributes>
    <toc>left</toc>
    <icons>font</icons>
    <imagesdir>images</imagesdir>
    <source-highlighter>coderay</source-highlighter>
</attributes>

<properties>
  <my-site.version>2.3.0</my-site.version> (1)
</properties>

<embedded/>
<sectnums>true</sectnums>
<linkcss>false</linkcss>

embeds the CSS file and images into the output, defaults to false

enables to specify the location to one or more gem installation directories (same as GEM_PATH environment var), empty by default

a List<String> to specify additional Ruby libraries not packaged in AsciidoctorJ, empty by default

List of extensions to include during the conversion process (see AsciidoctorJ’s Extension API for information about the available options). For each extension, the implementation class must be specified in the className parameter, the blockName is only required when configuring a BlockProcessor, BlockMacroProcessor or InlineMacroProcessor.

<plugin>
    ...
    <executions>
        <execution>
            <configuration>
                ...
                <extensions>
                    <extension>
                        <className>org.asciidoctor.maven.SomePreprocessor</className>
                    </extension>
                    <extension>
                        <className>org.asciidoctor.maven.SomeBlockProcessor</className>
                        <blockName>yell</blockName>
                    </extension>
                </extensions>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency> (1)
            <groupId>org.asciidoctor.maven</groupId>
            <artifactId>my-asciidoctor-extensions</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</plugin>

enables Asciidoctor verbose messages, defaults to false. Enable it, for example, if you want to validate internal cross references and capture the messages with the logHandler option.

enables processing options for Asciidoctor messages (e.g. errors on missing included files), to either hide messages or setup build fail conditions based on them. Options are: