asciidoctor-ant Task

The asciidoctor-ant is the official means of using Asciidoctor to render all your AsciiDoc documentation using Apache Ant.

Installation

Prerequesites

• Java (minimum JDK 1.7)

• Ant (minimun Ant 1.8.0)

Download

You can download the uber jar of asciidoctor-ant in Maven Central. This jar contains the Ant task and its dependencies : JRuby and asciidoctorj.

Using Ant

...
      <get src="http://repo1.maven.org/maven2/org/asciidoctor/asciidoctor-ant/${asciidoctor-version}/asciidoctor-ant-${asciidoctor-version}.jar"
           dest="lib/asciidoctor-ant.jar" usetimestamp="true"/>
...

Note	you can also download a core artifact without the asciidoctorj dependencies (available since 1.5.4).

Usage

<project xmlns:asciidoctor="antlib:org.asciidoctor.ant">
...
    <target name="doc">
        <taskdef uri="antlib:org.asciidoctor.ant" resource="org/asciidoctor/ant/antlib.xml" classpath="lib/asciidoctor-ant.jar"/> (1)
        <asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target"/>
    </target>
...
</project>

1. "lib" is a directory containing the uber jar asciidoctor-ant.jar

Configuration options

There are several configuration options that the asciidoctor-ant Task uses. The options are similar to asciidoctor-maven-plugin :

sourceDirectory

the source directory of Asciidoc files (mandatory)

sourceDocumentName

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

outputDirectory

the ouput directory (mandatory)

baseDir

(not ant’s basedir) enables to set the root path for resouces (e.g. included files), defaults to Ant project base directory

preserveDirectories

enables to specify whether the documents should be rendered 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

relativeBaseDir

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

imagesDir

defaults to images, which will be relative to the directory containing the source files

backend

defaults to docbook

doctype

defaults to article

eruby

defaults to erb, the version used in jruby

headerFooter

defaults to true

compact

defaults to false

templateDir

disabled by default, defaults to null

templateEngine

disabled by default

sourceHighlighter

enables and sets the source highlighter (currently coderay or highlightjs are supported)

extensions

a list of non-standard extensions to render separated by comma. Currently ad, adoc, and asciidoc will be rendered by default

embedAssets

embed the CSS file, etc into the output, defaults to false

safemode

set SAFE mode. Possible value are safe, secure, server, unsafe. Not required - default is safe.

gemPaths

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

Builtin attributes

You can set attributes with nested <attribute>. There are various attributes Asciidoctor recognizes. Below is a list of them and what they do :

title

An override for the title of the document.

Example

...
    <asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target">
        <attribute key="title" value="Asciidoc Ant"/>
    </asciidoctor:convert>
...

Many other attributes are possible. See http://asciidoctor.org/docs/user-manual/#builtin-attributes for the full list.

Resources (images, css, …​)

With nested <resource>, the external resources used by your document can be copied to output directory.

Example

...
    <asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target" backend="html5">
        <resource dir="src/asciidoc/images" includes="*.png,*.jpg"/>
    </asciidoctor:convert>
...

AsciidoctorJ Extensions

You can register AsciidoctorJ extensions with nested extensions elements :

Type	Attributes
preProcessor	className
treeProcessor	className
postProcessor	className
blockProcessor	blockName and className
blockMacroProcessor	blockName and className
inlineMacroProcessor	blockName and className
includeProcessor	className

Example

...
    <asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target" backend="html5">
        <inlineMacroProcessor blockName="twitter" className="org.asciidoctor.ant.extensions.TwitterMacro"/>
    </asciidoctor:convert>
...

Additional Ruby libraries

You can specify additional Ruby libraries not packaged in AsciidoctorJ.

Example

...
    <asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target" backend="html5" gemPaths="gems-provided">
      <require name="tilt"/>
      <require name="haml"/>
      <require name="asciidoctor-diagram"/>
    </asciidoctor:convert>
...

Note	you have to give a path to find gems with gempPaths attribute.