DITA Open Toolkit Gradle Plugin

A fast, versatile, and pleasant DITA publishing experience.

DITA-OT Gradle Plugin is a Gradle plugin for publishing DITA documents that's more powerful and faster than using DITA Open Toolkit directly.

Backed by the full power of Gradle, you can also use DITA-OT Gradle Plugin for more complex publishing scenarios, such as the one for this website.

Choose your operating system:

Features

Performance

Depending on the size of your document, DITA-OT Gradle Plugin can magically decrease your publishing times by up to 70%1 after the first run. The difference is more noticeable with small or medium documents.

Here's a graph that shows the development of the publishing duration in seconds over 50 runs for the DITA-OT user guide with and without the DITA-OT Gradle Plugin2:

Note:

You must have the Gradle Daemon enabled to get the performance benefit.

The performance improvement is due to the Gradle Daemon, which effectively removes the JVM warmup time.

If you're feeling adventurous and you have a multi-project build, you can also try Gradle's --parallel option to build your documents in parallel and speed builds up even more. However, since DITA-OT isn't fully thread-safe, your builds might become unreliable.

Easy to configure

After you've installed Gradle3 and DITA-OT, using DITA-OT Gradle Plugin is simple. There's no need to use startcmd.bat or mess with your classpath: just create a a simple Gradle buildfile, run Gradle, and voilà: your published document should appear in your project's build directory (build by default).

Just like Gradle, DITA-OT Gradle Plugin works on all major platforms.

(The API is pretty nice, too.)

Versatile publishing

With DITA-OT Gradle Plugin, you easily publish large document sets in one go. If you want to publish every file with a ditamap extension in the dita subdirectory using the PDF transtype, do something like this:

dita {
    input fileTree(dir: 'dita', include: '*.ditamap')
    transtype 'pdf'
}

By default, DITA-OT Gradle Plugin looks for a properties file the has the same basename as your input file and that's in the same directory as your input file4 and uses any DITA-OT parameters you define in it to publish that input file.

You can combine these two features to publish many DITA map files at once and define document-specific properties (such as the location of the DITAVAL file).

If you want to define multiple DITA-OT publishing tasks in the same Gradle buildfile (if you want to publish the same document multiple times with different parameters, for example) you can use the alternative syntax for defining tasks:

import com.github.eerohele.DitaOtTask

task web(type: DitaOtTask) {
    input 'root.ditamap'
    transtype 'html5'
    filter 'web.ditaval'
}

task pdf(type: DitaOtTask) {
    input 'root.ditamap'
    transtype 'pdf'
    filter 'print.ditaval'

    properties {
      property name: 'args.rellinks', value: 'all'
    }
}

Incremental builds

DITA-OT Gradle Plugin checks whether your source files have changed5 and only runs DITA-OT if they have (or if you force it to by passing the --rerun-tasks option).

If you're publishing a large document set, you can set up a multi-project build and speed up the feedback cycle by publishing only those documents that have changed.

Continuous builds

You can also use Gradle's continuous build feature option to tell DITA-OT to automatically republish your document when it changes:

$ gradle --continuous
...
Waiting for changes to input files of tasks... (ctrl-d to exit)
Change detected, executing build...
...

This is especially useful when writing a small document or a single topic because it lets you see the effects of your changes fairly quickly.

Installing DITA-OT Gradle Plugin

  1. Install DITA Open Toolkit.

  2. Install Gradle.

    If you have Homebrew installed, you can just run brew install gradle.
    Gradle is probably available on your favorite package manager.
  3. Copy-paste this Gradle script into a file called build.gradle:

    Note: Replace the values indicated by the comments (lines that start with two forward slashes) with your own values.
    plugins {
        id 'com.github.eerohele.dita-ot-gradle' version '0.5.0'
    }
    
    defaultTasks 'dita'
    
    // Replace this with the path to your DITA-OT installation.
    // Note the forward slash instead of the backslash!
    ditaOt.dir 'C:/DITA-OT'
    
    dita {
        // Replace this with the path to the DITA file you want to publish.
        input 'my.ditamap'
    
        // Replace this with the format(s) you want to publish into.
        transtype 'html5', 'pdf'
    }
    plugins {
        id 'com.github.eerohele.dita-ot-gradle' version '0.5.0'
    }
    
    defaultTasks 'dita'
    
    // Replace this with the path to your DITA-OT installation.
    ditaOt.dir '/opt/dita-ot'
    
    dita {
        // Replace this with the path to the DITA file you want to publish.
        input 'my.ditamap'
    
        // Replace this with the format(s) you want to publish into.
        transtype 'html5', 'pdf'
    }
  4. In the directory where you saved build.gradle, run gradle.

    The output will appear in the build subdirectory of the directory where build.gradle is.

Options

The ditaOt task

Use the ditaOt task to tell DITA-OT Gradle Plugin about your DITA-OT installation.

Type Option Description
String | FiledirYour DITA-OT installation directory.
String...plugins

One or more DITA-OT plugins to install before publishing. For example:

plugins 'https://github.com/dita-ot/org.dita.normalize/archive/1.0.zip'
String...classpath

Augment or override the DITA-OT classpath. Typically, you only need to use this if you want to use a different version of Saxon than the one bundled with DITA-OT. For example:

classpath getDefaultClasspath(project).matching {
    exclude('**/saxon*.jar')
} + file('saxon9pe.jar')

The dita task

Use the dita task to define your DITA publishing scenario.

Type Option Description
String | FileinputThe input file.
String | FileoutputThe output directory. Default: build.
String...transtypeOne or more formats to publish into.
String | FilefilterThe DITAVAL file.
String | FiletempThe DITA-OT temporary directory.
BooleandevModeDetect changes in DITA-OT directory in addition to input DITA files. Useful for stylesheet developers. Default: false.
BooleansingleOutputDirMultiple input files ➞ single output directory. Default: false.
BooleanuseAssociatedFilterFor every input file, use DITAVAL file in same directory with same basename. Default: false.

Acknowledgements

1 This figure only holds for relatively small documents where the overhead of creating the Java Virtual Machine (JVM), loading classes, compiling XSLT stylesheets, and so on takes up more time than the actual processing. If your document takes 30 minutes to process now, it won't take 9 minutes with DITA-OT Gradle Plugin: more like 28 minutes, most likely.
2 DITA Open Toolkit 2.2 (development version), Gradle 2.7, MacBook Pro, 2,5 GHz Intel Core i5, 8 GB 1600 MHz DDR3.
3 If you're on OS X or Linux, installing Gradle is painless. On Windows, you'll have to set at least one environment variable, unfortunately.
4 For example, if your DITA map file is called my-awesome-document.ditamap, DITA-OT Gradle Plugin looks for a file called my-awesome-document.properties in the same directory as that file.
5 It currently checks whether any of the files under the directory where your source file is have changed. If you have files outside that directory, DITA-OT Gradle Plugin can't detect changes to those files.