Stefan Sobek v3.0 2017-02-07

This document is about how to install Asciidoctor.

Asciidoctor is a ruby tool for converting AsciiDoc content to HTML5, Docbook5 or other formats like pdf.

1. Installation on Mac

Usually newest Macs have Ruby already installed. To find out please do the following:

Open a Terminal on your Mac and type the following command:

ruby --version

You should see something like:

ruby --version
ruby 2.0.0p648 (2015-12-16 revision 53162) [universal.x86_64-darwin16]

Then install asciidoctor ruby gem:

gem install asciidoctor
asciidoctor --version

should show something like:

Asciidoctor 1.5.5 [http://asciidoctor.org]
Runtime Environment (ruby 2.0.0p648 (2015-12-16 revision 53162) [universal.x86_64-darwin16]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

Now you are done.

2. Installation on Linux

Open a Terminal on your Linux machine type the following command:

ruby --version

You should see something like:

ruby --version
ruby 2.0.0p648 (2015-12-16 revision 53162) [universal.x86_64-darwin16]

Then install asciidoctor ruby gem:

gem install asciidoctor
asciidoctor --version

should show something like:

Asciidoctor 1.5.5 [http://asciidoctor.org]
Runtime Environment (ruby 2.0.0p648 (2015-12-16 revision 53162) [universal.x86_64-darwin16]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

Now you are done.

3. Installation on Windows

Usually Windows will not have ruby installed. Thus first you have to install Ruby:

Download the rubyinstaller under https://rubyinstaller.org/ then execute the file and install it.

Please make sure you check the Option "Add Ruby executable to your path" during installation routine!!! Otherwise Windows cannot call the ruby command!!!

Now open a Windows Command Shell (WIN + type CMD) and install the asciidoctor gem:

gem install asciidoctor
asciidoctor --version

should show something like:

Asciidoctor 1.5.5 [http://asciidoctor.org]
Runtime Environment (ruby 2.0.0p648 (2015-12-16 revision 53162) [universal.x86_64-darwin16]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

4. How to convert an adoc file to html

Open a text editor or asciidoc editor of your choice, or use plugins in development tools.

E.g. you have a Use case description like:

[cols="1,3a"]
|===
|Name|Very nice use case
|Actor|Fantastic user
|Description|Blablabla
|Precondition|Blablabla
|Scenario|
. Step
. Another step
. Yet another step
|Result|Blablabla
|Exceptions|Blablabla
|===

You save that file as usecase.adoc.

Now open your (Bash|Terminal|Command) Line and type:

asciidoctor usecase.adoc

Now a HTML file will be created named usecase.html.

If there are some errors returned with line numbers given where it occurs, correct them and rerun the command.

That’s it.