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.
Use the following snippet inside a Gradle build file:
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'org.asciidoctor:asciidoctor-gradle-plugin:0.8.0.SNAPSHOT'
}
}
apply plugin: 'asciidoctor'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: |
| sourceDocumentName |
an override to process a single source file. Type: File. Defaults to all files in |
| sourceDocumentNames |
an override to process multiple source files, which may be a subset of all
files available in |
| outputDir |
where generated docs go. Type: File. Default: |
| backend |
the backend to use. Type: String. Default: |
| backends |
the backends to use. Type: Set<String>. Default: [ |
| 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: |
Sources may have any of the following extensions in order to be discovered
-
.asciidoc
-
.adoc
-
.asc
-
.ad
The following attributes are automatically set by the Asciidoctor task
-
project-name : matches $project.name
-
project-version: matches $project.version (if defined). Empty String value if undefined
-
project-group: matches $project.group (if defined). Empty String value if undefined
These attributes may be overridden by explicit user input.
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
// 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.
<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:
attributes: [
// ...
docinfo1: '',
// ...
]The value of attributes my be specified as a Map, List, Array or String, for example the following Map definition
options = [
attributes: [
toc: 'right',
'source-highlighter': 'coderay',
'toc-title': 'Table of Contents'
]
]may be rewritten in List/Array form as follows
options = [
attributes: [
'toc=right',
'source-highlighter=coderay',
'toc-title=Table of Contents'
]
]or in String form like so
options = [
attributes: 'toc=right source-highlighter=coderay toc-title=Table\\ of\\ Contents'
]Notice how spaces are escaped in the last key/value pair.
Refer to the Asciidoctor documentation to learn more about these options and attributes.
