Getting started with Asciidoctor
One of the best ways to get started with AsciiDoc is to use the Asciidoctor toolchain, and specifically the Gradle integration. Ironically, the documentation on how to do this is not always clear, so this blog is an attempt to make things a bit easier.
To get started with AsciiDoc and Gradle, we’ll create a new Gradle project, add the AsciiDoc support, and then create a small demo page to get you started. So, open a Terminal, and type the following commands:
|
1 2 3 |
mkdir my-project cd my-project gradle init |
The above will create a new empty Gradle project. Now, open the build.gradle to add the required configuration for AsciiDoc.
|
1 2 3 4 5 6 7 8 9 10 |
plugins { id 'org.asciidoctor.convert' version '1.5.2' } version = '1.0.0-SNAPSHOT' asciidoctor { attributes 'toc':'left' sources { include '*.adoc' } } |
The last thing we’ll have to do now is to create an intial document, and you’re ready to go. The default source document used by AsciiDoc is src/docs/asciidoc, so let’s create that directory:
|
1 |
mkdir -p src/docs/asciidoc |
Then, create a file in that directory. The extensions .ad, .asciidoc and .adoc are supported, where .adoc is the most widely used. I choose the file ‘test.adoc’:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
= Big title Some content here == A somewhat smaller title AsciiDoc supports: * *bold* text * _italic_ text * `mono` text * http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[And many more]! |
If you now run the AsciiDoc Gradle task, by executing the wrapper script: ./gradlew asciidoc, then a beautiful AsciiDoc HTML file called test.html should end up in build/asciidoc/html5.
