Gradle Plugin for downloading Asciidoctor PDF Themes

This Gradle plugin extends the asciidoctor-gradle-plugin. It clones a Git repository, which contains a theme for Asciidoctor PDF.

Motivation

You might wonder, what the use case for this plugin is.

Consider, you’re using Asciidoctor PDF in a corporate environment. You might want to customize the theme for Asciidoctor PDF. Normally, you would have to include a copy of the theme in every repository from that documents are built.

With this plugin, you can specify a git repository that contains your theme. When building the PDF using the Asciidoctor Gradle Plugin, this plugin downloads the theme and sets the required properties.

Example Theme

Here is an example repository for an Asciidoctor PDF theme. Please note that the structure of the repository is mandatory for this plugin to work. This means, that toplevel must be a directory resources.

For more information on Asciidoctor PDF themes, please consult Asciidoctor PDF Theming Guide.

Usage

Note	This plugin requires the asciidoctor-gradle-plugin and asciidoctorj-pdf.

Apply this plugin. Its plugin id is com.github.fwilhe.asciidoctor-pdf-theme.

To configure the theme, you need to specify a git repository and a name. The name is what comes before the -theme.yml for your Asciidoctor PDF theme.

theme {
    url = 'git@someserver:lorem/ipsum-theme.git'
    name = 'ipsum'
}

You may optionally specify themeVersion, which must be a git tag. If it is set, this tag will be checked out. Otherwise the master branch will be checked out.

Example Document using this Plugin

Here is an example gradle project using this plugin.

Development

For testing purposes, the plugin can be installed locally using

./gradlew publishToMavenLocal

After installing locally, the version latest of this plugin can be used in your build.gradle file.

Testing

The tests can also be run using Gradle with the following command:

./gradlew test

Versioning

I try to follow the Semantic Versioning strategy. This means, the version number can be read as <BREAKING>.<FEATURE>.<FIX>.

Release

• Update Changelog

• Update version in build.gradle

• Perform the release using Gradle

./gradlew release