Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A Gradle plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.

This branch is 211 commits behind asciidoctor:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
config/codenarc
gradle
src
.gitignore
.travis.yml
LICENSE.txt
README.adoc
build.gradle
gradle.properties
gradlew
gradlew.bat

README.adoc

Asciidoctor Gradle Plugin

Build Status

The asciidoctor-gradle-plugin is the official means of using Asciidoctor to render all your AsciiDoc documentation using Gradle.

This is a port of the asciidoctor-maven-plugin project by @LightGuard. Relies on asciidoctor-java-integration by @lordofthejars.

Installation

Use the following snippet inside a Gradle build file:

build.gradle
buildscript {
    repositories {
        mavenRepo name: 'Bintray Asciidoctor repo', url: 'http://dl.bintray.com/content/aalmiray/asciidoctor'
        mavenRepo name: 'Bintray JCenter', url: 'http://jcenter.bintray.com'
    }

    dependencies {
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:0.5.0'
    }
}

apply plugin: 'asciidoctor'

Usage

The plugin adds a new task named asciidoctor. This task exposes 6 properties as part of its configuration

sourceDir

where the asciidoc sources are. Type: File. Default: src/asciidoc.

sourceDocumentName

an override to process a single source file. Type: File. Defaults to all files in ${sourceDir}

outputDir

where generated docs go. Type: File. Default: $buildDir/asciidoc.

backend

the backend to use. Type: String. Default: html5.

options

a Map specifying different options that can be sent to Asciidoctor.

logDocuments

a boolean specifying if documents being processed should be logged on console. Type: boolean. Default: false

Sources may have any of the following extensions in order to be discovered

  • .asciidoc

  • .adoc

  • .asc

  • .ad

Configuration

The following options may be set using the task’s options property

  • header_footer - boolean

  • template_dir - String

  • template_engine - String

  • compact - boolean

  • doctype - String

  • attributes - Map

Any key/values set on attributes are sent as is to Asciidoctor. You may use this Map to specify an stylesheet for example. The following snippet shows a sample configuration defining attributes

build.gradle
// append below the line: apply plugin: 'asciidoctor'

asciidoctor {
    outputDir = new File("$buildDir/docs")
    options = [
        eruby: 'erubis',
        attributes: [
            'source-highlighter': 'coderay',
            toc: '',
            idprefix: '',
            idseparator: '-'
        ]
    ]
}

You may need to include extra content into the head of the exported document. For example, you might want to include jQuery inside the <head> element of the HTML export. To do so, first create a docinfo file src/asciidoc/docinfo.html containing the content to include, in this case the <script> tag to load jQuery.

src/asciidoc/docinfo.html
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.js"></script>

Then, add the docinfo1 attribute to the attributes list in the previous example:

build.gradle
attributes: [
    // ...
    docinfo1: '',
    // ...
]

Refer to the Asciidoctor documentation to learn more about these options and attributes.

History

0.5.0

0.4.1

  • Fixes #16. Property sourceDocumentName is mandatory.

0.4.0

  • Supports Asciidoctor 0.1.3

  • Fixes #13. Rendering under Windows fails.

  • Fixes #14. Stylesheet attributes cannot take a GString for a value.

  • Fixes #15. Provide sourceDocumentName as a property.

0.3.0

  • Supports Asciidoctor 0.1.2

  • Rely on asciidoctor-java-integration

0.2.2

  • Fixes #7. Make up-to-date directory detection work for AsciidoctorTask.

0.2.1

  • Fixes #6. Can’t run plugin if Gradle daemon is active.

0.2

  • Support Asciidoctor 0.1.1

  • Backends: html5, docbook

0.1

  • First release.

  • Supports Asciidoctor 0.0.9

  • Backends: html5

Something went wrong with that request. Please try again.