× Home Tutorials Training Consulting Products Books Company Donate Contact us









NOW Hiring

Quick links

Share

This tutorial contains some notes about writing documentation with AsciiDoc and Asciidoctor.

1. Introduction into Asciidoc

1.1. What is Asciidoc and Asciidoctor

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated via the Asciidoctor toolchain to many formats including HTML, PDF, EPUB, DocBook and man page. Any text editor can be used. Some websites, like Github, render AsciiDoc files directly into HTML.

The following listing is an example of a simple Asciidoc file.

== The First Asciidoc example
Lars Vogel(c) 2016 vogella GmbH
Version 0.2, 17.12.2015
:sectnums:                                                          (1)
:toclevels: 4 														(2)
:toc-title: My Content												(3)
:experimental:                                                      (4)
:description: Example AsciiDoc document                             (5)
:keywords: AsciiDoc                                                 (6)
:imagesdir: ./img 													(7)

This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.

== First section

Some text

== Second section

More test
1 this attribute defines the you want to numbered sections.
2 by default, the TOC will display only level 1 and level 2 section titles. With the toclevels attribute the level can be set differently.
3 by default, the TOC will get the title "Table of Contents", you can set a customized name with the toc-title attribute. This will apply for the html and pdf output.
4 enables experimental features, like button and menu paths
5 adds description to the HTML output
6 adds keywords to the HTML output
7 Defines the default image location Asciidoc documents typically ends with the .adoc.

1.2. Important outstanding issues in Asciidoctor

While Asciidoctor is awesome, several outstanding issues make the usage of the PDF output difficult. If you want to create PDF from Asciidoc, you most likely need first to create Docbook output and afterwards PDF from it.

Vote for issue

1.3. Install2 the Asciidoctor toolchain

If you want to use Asciidoctor directly you have to install its toolchain. If you are using Gradle or Maven as build systems, it is not required to install Asciidoctor separately. Both Gradle or Maven provide plug-ins to execute Asciidoctor tasks.

sudo apt-get install -y asciidoctor

2. Writing tips for great Asciidoc documents

2.1. One sentence per line

Try to write one sentence per line. This allows you to search this sentence easily and ensure you use concise descriptions which are easy to read. This also makes it easy to move sentence around in your favorite text editor.

Based on personal experience this rule makes a great difference in the generated text. It helps you to avoid complex sentence structures and helps to reduce redundancy in your text.

3. Basic document features

3.1. Text formatting

Use the following to highlight your text.

*This is bold text*

_This is cursiv text_

`This is mono text`

The result looks like the following:

This is bold text

This is cursiv text

This is mono text

3.2. Force line breaks

A + (plus) at the end of a line with a following space forces a line break.

++SPACE

3.3. Importing files or file includes

You can import files via the include macro. This also works for source code includes. To use ---- in your listing use the [listing] style before that. The following example imports a file formatted as Java source code. Via the leveloffset attribute you can change the section offset, for example a = section will become == if you add the following statement :leveloffset: 1. Use :leveloffset: 0 to reset the offset.

[source,java]
----
include::res/source.java[]
----

Result:

System.out.println("Hello");

3.4. Importing files partially

It is also possible to include files partially. For this mark the part of the file to be included with a tag like the following:

//article.adoc
# tag::tagname[]
This should be included!
# end::tagname[]
This text will not be included!

and include the file with the tagname in the brackets like this:

include::article.adoc[tags=tagname]

The result would be

This should be included!

3.5. Importing images

You can import images with image:: for the HTML output you can add the alt text within the brackets []. If the image is located in the img folder then the import would look like this:

image::./img/vogellacompany.jpg[vogella Company]

If the images are located in a certain directory, e.g. img, you can specify this folder in the header of your document and the import of the image will only contain the name of the image without the name of the folder. Please note that you have to add a space between :imagesdir: and the name of the folder.

This would look as follows:

:imagesdir: ./img
image::vogellacompany.jpg[vogella Company]

The import of an image with image:: will add the image in a new line. If you want to add an image inline then use the macro: image:

This is just a text
image:vogellacompany.jpg[vogella Company, width=5%] to show inline images.

Result:

This is just a text vogella Company to show inline images.

3.6. Defining lists

Lists can be defined with the * operator at the beginning of a line. You can define up to 6 levels for a list. Ensure to have a space before the list element. Example:

Docker allows to package the full stack in a container:

* OS
** Windows
** Ubuntu
* JVM,
* App server
* Application with its configuration

Result:

  • OS

    • Windows

    • Ubuntu

  • JVM,

  • App server

  • Application with its configuration

Numbered lists start with the .

. OS
.. Windows
.. Ubuntu
. JVM,
. App server
. Application with its configuration

Result:

  1. OS

    1. Windows

    2. Ubuntu

  2. JVM,

  3. App server

  4. Application with its configuration

Additional paragraphs, blocks, images, source code, etc. are adjoined to a list element by putting a plus sign (+) on a line adjacent to both blocks.

* Listing1
* Listing2
+
image::vote-asciidoc-issue.png[]

Result:

  • Listing1

  • Listing2

    vote asciidoc issue

You can define menus and buttons. This requires the activation of an experimental feature, via the :experimental: attribute in the header section of your document.

menu:View[Zoom > Reset]

Press the btn:[OK] button when you are finished.

The result looks like the following.

View ▸ Zoom ▸ Reset.

Press the OK button when you are finished.

3.8. Keyboard shortcuts

You can also define keyboard shortcuts with the kbd macro.

kbd:[Alt+F11] - Toggle Full Screen Mode in the Eclipse IDE

The result is the following:

Alt+F11 - Toggle Full Screen Mode in the Eclipse IDE

3.9. Images and Graphics

To reference images in your AsciiDoc with the image:: macro pointing to a relative file location. Use brackets to define a fixed or related size.

image::vogellacompany.jpg[200,200]

The result looks like the following:

200

You can also define a text for the image which is for example used for screenreaders or as placeholder if the image cannot be found.

image::vogellacompany.jpg[vogella Logo, 200,200]

If you want to scale the image for the PDF output you can use the pdfwidth attribute.

image::vogellacompany.jpg[vogella Logo,pdfwidth=40%]

You can also define a default image width via the PDF theming support.

3.10. Using inline icons

You can also add the :icons: font directive to the top of your document, which allows you to use the icons from http://fortawesome.github.io/Font-Awesome/icons/ directory via a marco.

icon:comment[] This is a comment icon

icon:file[] And a file icon

icon:battery-full[] And a battery icon

The output looks like the following

This is a comment icon

And a file icon

And a battery icon

Asciidoc determines automatically links in the content of your document, if the link starts with http:// or https://. You can also define a anchor text via [] directly after the link.

http://www.vogella.com[vogella]

http://www.vogella.com

The result looks like the following.

In order to include a link with white spaces or special characters as for example

https://vogella.com--sa- 23345

the definition should look like this:

link:++https://vogella.com--sa- 23345++

3.12. Defining cross references

You can assign meta data to a block. Here’s an example of a quote block that includes all types of metadata:

.Topic Titel                                               (1)
[[yourId]]                                                 (2)
[yourstyle]                                                (3)
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...

Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure.
____
1 title of the block
2 reference for the block
3 can be used to style the corresponding block.

You can link to the references via, for example

You find more information on this in <<yourId>>.

3.13. Table

You can create also tables in Asciidoc via the following syntax.

.Table Title
|===
|Name of Column 1 |Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===

The result looks like the following.

Table Title

Name of Column 1 Name of Column 2

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

You can also define the relative table width.

.Table with relative column widths (1,3)
[cols="1,3",options="header"]
|===
| Name | Description
| Testing
| Table width
|===

Of course you can define tables with more than two columns.

.Table Title
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3

|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===

3.13.1. Define column widths

The [cols="1,3"] declaration directly underneath the .Table declaration can be used to specify the column’s width. If the width is set then the option="header" must also be set like this: [cols="1,3",options="header"] in order to see the first row of a table as a header.

.Table Title
[cols="1,3",options="header"]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3

|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===

The snippet above will result in the following:

Table 1. Table Title
Name of Column 1 Name of Column 2

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Alternatively % values can be used, e.g., [cols="40%, 60%"].

In order to add special asciidoc elements as lists, notes, sourcecode, etc. within a table cell just add an a before the |. Some elements like keyboard shortcuts(kbd) and buttons(btn) do not need a special definition in tables. This would look like this:

.Table with asciidoc elements
|===
|Keyboard shortcut |List |Note |Button

|kbd:[Ctrl+9]
a|* Test 1
* Test 2
* Test 3
a|
[NOTE]
====
This is a good idea
====
|btn:[OK]

|===
Table 2. Table with asciidoc elements
Keyboard shortcut List Note Button

Ctrl+9

  • Test 1

  • Test 2

  • Test 3

This is a good idea

OK

3.14. Source code, using monospace and callouts

Use monospace text formatting to emulate how source code appears in computer terminals, simple text editors, and integrated development environments (IDEs). Enclose the starting hypthen string with \ for this, e.g., `System.out.println("Hello");` results in System.out.println("Hello");

To enable syntax highlighting in the output, set the style on the block to source and specify the source language in the second attribute position.

[source, java]
----
include::res/test.java
----

The supported languages depends on your renderer but your can for example use:

  • console - for terminal output

  • java - for Java source files

It is also very simple to add callouts, as demonstrated by the following snippet.

[source, java, numbered]
----
System.out.println("Hello");  # <1>
private int a;
----
<1> Imports the library

Output is the following

1
2
System.out.println("Hello");  (1)
private int a;
1 Imports the library

Supported types are java, xml, terminal

3.15. Escape special signs

If you need to escape Asciidoc commands, you can use \ before the character that would normally be interpreted by Asciidoc. To write for example | you would need to write it like this: \|.

3.16. Index

You can add primary index terms to your document via (((yourterm))). A secondary index can be added to your document via (((yourterm, secondary term2))). For example:

((((Big cats)))

((((Big cats, Lions)))

3.17. Comments in Asciidoc

We can add comments to the Asciidoc markup. The comments are not added to the generated output. You can use both single and multiline comments. Single line comments start with a double slash (//). Multiline comments are enclosed in a block of four forward slashes (////).

3.18. Escape Asciidoc markup

Most AsciiDoc elements can be escaped by preceding them with a backslash character.

3.19. Custom attributes / variables

You can define custom variables and use them in your document. For example the following defines the variable yourvariable which can be used with {yourvariable} and Asciidoctor will replace it with the value defined after the second :.

:yourvariable: vogella

4. Conversion with Asciidoctor

You will need a working Ruby installation. For our installation guide see: http://www.vogella.com/tutorials/Ruby/article.html

4.1. Asciidoctor installation

To convert your asciidoc files you need to install the Asciidoctor gem.

gem install asciidoctor

If you want to be able to create pdf-files you can use the asciidoctor-pdf gem.

gem install --pre asciidoctor-pdf

4.2. Converting AsciiDoc to html5

Because Asciidoctor will default to the html5 backend you don’t need to call it with any extra arguments.

asciidoctor example.adoc
# defaults to
asciidoctor -b html5 example.adoc

To see a list of all available backends you can call asciidoctor --help.

4.3. Converting AsciiDoc to pdf-files

After the installation of the gems you are ready to convert your AsciiDoc files to pdf-format.

asciidoctor-pdf example.adoc

4.4. Using the development version of Asciidoctor to create pdf-files

If you want to use the latest development version of asciidoctor to create your pdf-files you have to clone the asciidoctor-pdf repository from Github.

git clone git@github.com:asciidoctor/asciidoctor-pdf.git

To get the application ready you first need to install the dependencies. You might have to install the bundler gem first.

cd asciidoctor-pdf
bundle install

Now you can start using the latest version to convert your AsciiDoc.

./bin/asciidoctor-pdf /path/to/your/file.adoc
# or via bundler
bundle execute asciidoctor-pdf /path/to/your/file.adoc

4.5. Using Asciidoctor in a Gradle build file

4.5.1. Using AsciidoctorJ in a Gradle build

The easiest way to use Asciidoctor in a Gradle build is through the Asciidoctor Gradle Plugin. It is based on AsciidoctorJ, which functions as a Java wrapper for Asciidoctor.

The following example build.gradle will convert your source files to html5.

plugins {
    id 'org.asciidoctor.convert' version '1.5.3'
}

apply plugin: 'java'
apply plugin: 'org.asciidoctor.convert'

asciidoctorj {
    version = '1.5.4'
}

asciidoctor {
    attributes \
        'build-gradle': file('build.gradle'),
        // point this to the folder that holds your AsciiDoc
        'sourcedir': project.sourceSets.main.java.srcDirs[0],
        'endpoint-url': 'http://example.org',
        'source-highlighter': 'coderay',
        'imagesdir': 'images',
        'toc': 'left',
        'icons': 'font',
        'setanchors': '',
        'idprefix': '',
        'idseparator': '-',
        'docinfo1': ''
}

You start the conversion by invoking the asciidoctor task.

gradle asciidoctor

4.5.2. Using the Asciidoctor-Pdf gem in a Gradle build

You can use the latest Ruby version of Asciidoctor extensions directly in your Gradle build. The following example shows how to use the asciidoctor-pdf gem.

plugins {
    id 'org.asciidoctor.convert' version '1.5.3'
    id 'com.github.jruby-gradle.base' version '1.3.3'
}

apply plugin: 'org.asciidoctor.convert'

dependencies {
    gems 'rubygems:asciidoctor-pdf:1.5.0.alpha.13'
}

asciidoctorj {
    version = '1.5.4.1'
}

asciidoctor {
    // jrubyPrepare downloads and installs Ruby Gem dependencies
    dependsOn jrubyPrepare
    // include the 'asciidoctor-pdf' Ruby module
    requires = ['asciidoctor-pdf']
    // let the Asciidoctor Plugin search for Gems in jrubyPrepares output directory
    gemPath = jrubyPrepare.outputDir
    // convert to pdf
    backends 'pdf'
}

You start the conversion by invoking the asciidoctor task.

gradle asciidoctor

4.5.3. Using the development version of Asciidoctor-Pdf in a Gradle build file

To use the development version of Asciidoctor-Pdf in a Gradle build file you first need to build the gem.

git clone git@github.com:asciidoctor/asciidoctor-pdf.git
cd asciidoctor-pdf
bundle
bundle exec rake build

You can then find the .gem file under /pkg. Copy it into your Gradle project under the folder development-gems.

We are going to use the JRuby and Asciidoctor Gradle plugin, so we need to declare them.

plugins {
  id 'org.asciidoctor.convert' version '1.5.3'
  id 'com.github.jruby-gradle.base' version '1.3.3'
}

apply plugin: 'org.asciidoctor.convert'

To use a local gem from Gradle, all dependencies of that gem have to be specified manually. You can find the dependencies in asciidoctor-pdf.gemspec

Gem::Specification.new do |s|
  # ...
  s.add_runtime_dependency 'prawn', '>= 1.3.0', '< 3.0.0'
  s.add_runtime_dependency 'prawn-table', '0.2.2'
  s.add_runtime_dependency 'prawn-templates', '0.0.3'
  s.add_runtime_dependency 'prawn-svg', '>= 0.21.0', '< 0.26.0'
  s.add_runtime_dependency 'prawn-icon', '1.3.0'
  s.add_runtime_dependency 'safe_yaml', '~> 1.0.4'
  s.add_runtime_dependency 'thread_safe', '~> 0.3.5'
  s.add_runtime_dependency 'treetop', '1.5.3'
end

You can then add them to your build.gradle.

dependencies {
  gems 'rubygems:prawn:2.1.0'
  gems 'rubygems:prawn-table:0.2.2'
  gems 'rubygems:prawn-templates:0.0.3'
  gems 'rubygems:prawn-svg:0.25.2'
  gems 'rubygems:prawn-icon:1.3.0'
  gems 'rubygems:safe_yaml:1.0.4'
  gems 'rubygems:thread_safe:0.3.5'
  gems 'rubygems:treetop:1.5.3'
}

You need to override the jrubyPrepare task to use all of the declared dependencies plus the local gem.

import com.github.jrubygradle.JRubyPrepare
task customJRubyPrepare(type: JRubyPrepare) {
  dependencies project.configurations.gems
  dependencies file('development-gems/asciidoctor-pdf-1.5.0.alpha.14.dev.gem')
  outputDir buildDir
}

Finally you have to make sure that the asciidoctor task depends on customJRubyPrepare and requires asciidoctor-pdf.

asciidoctor {
    dependsOn customJRubyPrepare
    requires ['asciidoctor-pdf']
    gemPath customJRubyPrepare.outputDir
    backends 'pdf'
}

Trigger the asciidoctor task to convert your AsciiDoc.

gradle asciidoctor

5. Admonition paragraphs and blocks for warnings, notes and tips

5.1. Admonition paragraphs

An admonition paragraph draws the reader’s attention to certain information. It can be defined by a predefined label at the beginning of the paragraph or as a block.

Here are the other built-in admonition types:

NOTE: Some additional info...

TIP: Pro tip...

IMPORTANT: Don't forget...

WARNING: Watch out for...

CAUTION: Ensure that...

The result looks like the following:

Here are the other built-in admonition types:

Some additional info..
Pro tip…​
Don’t forget…​
Watch out for…​
Ensure that…​

5.2. Admonition blocks

You can also use admonition blocks.

[TIP]
====
Think of c1..c2 as _all commits as of c1 (not including c1) until commit
c2._
====

The output looks like the following.

Think of c1..c2 as all commits as of c1 (not including c1) until commit c2.

Similar to a tip, you can add a warning.

[WARNING]
====
This is a warning
====

The output looks like the following.

This is a warning

The following styles are supported:

  • NOTE

  • TIP

  • IMPORTANT

  • CAUTION

  • WARNING

You can also add header to these admonitions.

.My header for the note
[NOTE]
====
Blabla
====

This looks like the following:

My header for the note

Blabla

5.3. Block quotes

[quote, Ben Parker, Spiderman Movie]
____
With great power comes great responsibility.
____

will look like this:

With great power comes great responsibility.

— Ben Parker
Spiderman Movie

6. Using the Eclipse IDE as Asciidoc editor

Different editors for AsciiDoc can be used within the Eclipse IDE. For instance the Mylyn Wiki Text plugin provides functionality to edit AsciiDoc files within the Eclipse IDE.

The Mylyn WikiText Extras feature can be installed from the http://download.eclipse.org/mylyn/snapshots/nightly/docs/ update site.

Mylyn WikiText Updatesite

It provides an editor and a preview tab for Asciidoc.

Mylyn WikiText Extras

One nice feature is that if you hold the CTRL (Command key on Mac), you can open files included with the include:: directive. This is depicted in the following screenshot.

mylyn hyperlinking10

Different outputs from the AsciiDoc file can be generated by using the WikiText popup menu of an AsciiDoc file.

WikiText Popup Menu

More information can be found here: https://wiki.eclipse.org/Mylyn/WikiText/AsciiDoc

7. Settings for the PDF output

To see the links in the generated output use the following attribute in the header of you document.

:show-link-uri:
Before release alpha.13 you have to use the :showlinks: attribute instead.

Also you can configure the label for a chapter via the chapter-label attribute, e.g. if you do not want any label you can use:

:chapter-label:

Unfortunately Asciidoctor does not add a page break before a part if you use "book" as output. See https://github.com/asciidoctor/asciidoctor-pdf/issues/329. As workaround you have to put manual line breaks into it with <<<.

7.2. Index

You can add an index to your pdf output by defining it as follows:

[index]
= Index

This will list all the defined indexes. The output will look like this:

index

7.3. Appendix

The appendix is defined as follows:

[appendix]
= Appendix

7.4. Styling the PDF output

In order to style the PDF output use the file basic-theme.yml in folder themes. In this file you can style the title page, the headings (h1, h2, h3, etc), the images and many more objects.

For example to style the heading do the following entry in the basic-theme.yml file:

heading:
  font_style: bold
  h1:
    font_color: 999999
    font_style: italic
    align: right

A useful feature is to set a default width for images in the pdf output. To achieve this do the following entry:

image:
  width: 60%

To see all possible styling settings visit the Asciidoc theming guide.

7.5. Publishing Mode

In order to use some publishing attributes you must set the media attribute in the header of your AsciiDoc document as follows:

:media: prepress

This attribute will trigger the following settings:

  • Double-sided (mirror) page margins

  • Automatic facing pages

7.5.1. Double-sided (mirror) page margins

The double-sided page margins will have the following impact: the page margins for the recto (right-hand, odd-numbered) and verso (left-hand, even-numbered) pages will be replaced by the side page margins with the values of the page_margin_inner and page_margin_outer keys.

You can define the page_margin_inner and page_margin_outer in the theme. This will look as follows:

page:
  margin: [0.5in, 0.67in, 0.67in, 0.67in]
  margin_inner: 0.75in
  margin_outer: 0.59in

These settings will trigger the following change to the output:

recto page margin
[0.5in, 0.59in, 0.67in, 0.75in]

verso page margin
[0.5in, 0.75in, 0.67in, 0.59in]

7.5.2. Automatic facing pages

Regarding to the automatic facing pages, a blank page will be inserted, if necessary, to ensure the following pages are right-hand-facing pages:

  • Title page

  • Table of contents

  • First page of body content

  • Parts and chapters

It’s possible to disable the automatic facing feature for a given part or chapter. This can be done by adding the nonfacing option [%nonfacing] to the section node. When the nonfacing option is present, the part or chapter title will be placed on the following page.

[%nonfacing]
= Chapter Title

Chapter content

8. Generating different output for AsciiDoc

8.1. Convert to DocBook

To convert asciidoc into DocBook use the following command:

asciidoctor -b docbook45 inputfile.adoc.

8.2. Include content into the header of our HTML or Docbook output

You can add content to the header of the HTML output. See http://asciidoctor.org/docs/user-manual/#docinfo-file for details.

9. About this website

10. Asciidoc resources

10.1. vogella GmbH training and consulting support

TRAINING SERVICE & SUPPORT

The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”.

The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.

Copyright © 2012-2016 vogella GmbH. Free use of the software examples is granted under the terms of the EPL License. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.

See Licence.