About
This repository contains examples on how to use Gradle and Asciidoctor to create html5, pdf, epub, deck.js, and reveal.js outputs.
1. Diagrams HTML Example
An example project that demonstrates how to convert AsciiDoc with diagrams to HTML5 using the Asciidoctor Gradle plugin.
1.1. Usage
Convert the AsciiDoc to HTML5 by invoking the 'asciidoctor' goal:
$ ./gradlew asciidoctor
Open the file build/asciidoc/html/example-manual.html in your browser to see the generated HTML file.
1.2. Source
1.3. Outputs
2. HTML, PDF, DocBook & epub3 Example
An example project that demonstrates how to convert AsciiDoc to HTML, PDF, DocBook & epub3 using the Asciidoctor Gradle plugin.
2.1. Usage
Convert the AsciiDoc to HTML, PDF, DocBook & epub3 by invoking the 'asciidoctor' goal:
$ ./gradlew asciidoctor
Open the file build/asciidoc/epub3/example-manual.epub in your browser to see the generated epub file.
Open the file build/asciidoc/html5/example-manual.html in your browser to see the generated HTML file.
Open the file build/asciidoc/pdf/example-manual.pdf in your browser to see the generated PDF file.
Open the file build/asciidoc/pdf/example-manual.xml in your browser to see the generated DocBook file.
2.2. Source
3. deck.js Example
An example project that demonstrates how to convert AsciiDoc to deck.js using the Asciidoctor Gradle plugin.
3.1. Usage
Convert the AsciiDoc to deck.js by invoking the 'asciidoctor' goal:
$ ./gradlew clean asciidoctor
3.2. IntelliJ
If you’re using IntelliJ you can generate the IDE’s files via:
$ ./gradlew idea
Open the file build/asciidoc/deckjs/example-manual.html in your browser to see the generated deckjs file.
3.3. Source
3.4. Outputs
4. HTML Example
An example project that demonstrates how to convert AsciiDoc to PDF through the docbook AsciiDoctor plugin and then the jdocbook gradle plugin.
Some notes:
-
I found little canonical information. There is a lot of trial-and-error here.
-
The jdocbook plugin requires stylesheets. They were taken from the spring "docbook-reference-plugin".
-
The stylesheet requires java-libraries. The two that were needed to build this documentation were (xslthl and saxon) were taken from https://github.com/spring-gradle-plugins/docbook-reference-plugin/blob/master/build.gradle.
4.1. Usage
Convert the AsciiDoc to HTML5 by invoking the 'asciidoctor' goal:
$ ./gradlew buildDocs
Open the file build/asciidoc/html/example-manual.html in your browser to see the generated HTML file.
4.2. Source
4.3. Outputs
5. epub3 Example
An example project that demonstrates how to convert AsciiDoc to epub3 using the Asciidoctor Gradle plugin.
5.1. Usage
Convert the AsciiDoc to epub3 by invoking the 'asciidoctor' goal:
$ ./gradlew asciidoctor
Open the file build/asciidoc/epub3/example-manual.epub in your browser to see the generated epub3 file.
5.2. Source
5.3. Outputs
6. Publish to GitHub Pages Example
An example project that demonstrates how to publish the HTML generated by the Gradle AsciiDoctor Plugin to GitHub pages using the Gradle Git Plugin.
6.1. Setup
You’ll need to do the following:
-
Create a personal access token in Github (found within Settings → Applications).
-
Create a gh-pages branch within your destination git repository.
-
Modify you build.gradle and gradle.properties files (see below).
githubPages {
repoUri = 'https://github.com/asciidoctor/asciidoctor-gradle-examples.git' (1)
credentials { (2)
username = project.hasProperty('githubToken') ? project.githubToken : ''
password = ''
}
pages {
from 'build/asciidoc/html5'
}
}
| 1 | The repoUri property should be set to the destination repo. |
| 2 | Use the personal access token from step 1 to set the githubToken property in a gradle.properties file within the root of the project or better yet in ~/.gradle/gradle.properties |
6.2. Usage
-
Add your asciidoc files to
src/docs/asciidoc -
./gradlew publishGhPages
6.3. Source
6.4. Outputs
7. HTML Example
An example project that demonstrates how to convert AsciiDoc to HTML5 using the Asciidoctor Gradle plugin.
7.1. Usage
Convert the AsciiDoc to HTML5 by invoking the 'asciidoctor' goal:
$ ./gradlew asciidoctor
Open the file build/asciidoc/html/example-manual.html in your browser to see the generated HTML file.
7.2. Source
7.3. Outputs
8. LiveReload HTML Example
An example project that demonstrates how to convert AsciiDoc to HTML5 using the Asciidoctor Gradle plugin with Live Reload support.
8.1. Usage
Convert the AsciiDoc to HTML5 by invoking the 'asciidoctor' goal:
$ ./gradlew asciidoctor
Open the file build/asciidoc/html/example-manual.html in your browser to see the generated HTML file.
8.2. Live Reload Support
The Gradle build also can support Live Reload
Start by running the build with Gradle 2.5+ continuous build feature.
$ ./gradlew -t asciidoctor
This ensures if you modify example-manual.adoc then everything is rebuilt.
Open another terminal and run the liveReload task:
$ ./gradlew liveReload
Now you can use the Chrome or Firefox plugins to automatically reload your browser when the build completes.
| After installing the Chrome LiveReload extension, you need to check the "Allow access to file URLs" checkbox in Tools > Extensions > LiveReload in order for it to work with local files. |
Now try editing example-manual.adoc and watching your browser. After a brief wait you will observe that the browser is automatically updated with your changes.
8.3. Source
8.4. Outputs
9. PDF Example
An example project that demonstrates how to convert AsciiDoc to PDF using the Asciidoctor Gradle plugin.
9.1. Usage
Convert the AsciiDoc to PDF by invoking the 'asciidoctor' goal:
$ ./gradlew asciidoctor
Open the file build/asciidoc/pdf/example-manual.pdf in your browser to see the generated PDF file.
9.2. Source
9.3. Outputs
10. Asciidoctor Gradle Plugin: AsciiDoc to (themed) PDF Example
An example project that demonstrates how to convert AsciiDoc to PDF using Asciidoctor PDF with the Asciidoctor Gradle plugin.
This example produces a book and makes use of a YAML style sheet (defined in src/docs/asciidoc/theme).
The rendered document is created in the build/pdf directory.
10.1. Usage
Convert the AsciiDoc to PDF using Asciidoctor PDF by invoking the asciidoctor task (configured as the default task):
$ ./gradlew
This example is based on this maven example.
10.2. Source
10.3. Outputs
11. reveal.js Example
An example project that demonstrates how to convert AsciiDoc to reveal.js using the Asciidoctor Gradle plugin.
11.1. Usage
Convert the AsciiDoc to reveal.js by invoking the 'asciidoctor' goal:
$ ./gradlew clean asciidoctor
11.2. IntelliJ
If you’re using IntelliJ you can generate the IDE’s files via:
$ ./gradlew idea
Open the file build/asciidoc/reveal/example-manual.html in your browser to see the generated revealjs file.