Tips and Tricks

Fail on missing attributes

Attributes whose value cannot be resolved are ignored by default and not shown as error or warning. If you need to, this behavior can be modified using the missing-attribute attribute.

Combining it with logHandler option it is possible to report an error and abort a build in case of missing attributes.

<configuration>
    <attributes>
        <attribute-missing>warn</attribute-missing>
    </attributes>
    <logHandler>
        <failIf>
            <severity>WARN</severity>
        </failIf>
    </logHandler>
</configuration>

Generate your documentation in separate folders per version

Use Maven project.version property to create dedicated custom output directories.

<configuration>
    ...
    <outputDirectory>target/generated-docs/${project.version}</outputDirectory>
    ...
</configuration>

Enable section numbering

Enable section numbering in the build using the attributes section.

<configuration>
    ...
    <attributes>
        ...
        <sectnums>true</sectnums>
        ...
    </attributes>
    ...
</configuration>

Add version and build date to the header

Automatically add version details to header and footer to all documents.

<properties>
   <maven.build.timestamp.format>yyyy-MM-dd HH</maven.build.timestamp.format>  (1)
</properties>

<configuration>
    ...
    <attributes>
        ...
        <revnumber>${project.version}</revnumber>
        <revdate>${maven.build.timestamp}</revdate>
        <organization>${project.organization.name}</organization>
    </attributes>
    ...
</configuration>

1	Add `maven.build.timestamp.format` to the pom’s properties section to set a custom date format.

Show Asciidoctor version

If you are not sure what version of the Asciidoctor converter is being used. You can obtain it using the version attribute like in the example blow.

Asciidoctor version: {asciidoctor-version}