Asciidoctor: A fun way of learning Asciidoc

Asciidoctor is an open source implementation of Asciidoc in Ruby. It is a fast, open source text processor and publishing tool. It is packed as a Ruby gem and is included in several Linux distros.

Writing is not an easy task but has evolved into an essential one. In the tech industry, documentation is very important for any software, as it contains information such as system requirements, the introduction of the software, its features, limitations and provisions for extension in its operations.

Writing emails is one thing, but writing technical documentation or any formal document is another matter altogether. Presentation plays a huge role while writing any document. When you are writing an email, you focus only on the content. People seldom worry about the format in their emails, but in a technical document, formatting your content has some significance. The font type and size, colour, spacing, indentation, line spacing, spaces between paragraphs and lists are all very important in a document.

So when you are typing your content in a word processor, your flow of thoughts tends to get interrupted by the continuous formatting required in it. Asciidoctor is a Ruby implementation of Asciidoc, which helps you to write tech documents as easily as writing a plain text document. Asciidoctor is based on the Ruby language. It comes with all the simplicity that any typical Ruby code possesses—it is easy to learn and you will be able to write content in Asciidoctor in no time.

Installation

Asciidoctor is a Ruby gem; so its installation is like any other Ruby gem you’ve installed in your system. Issue the following command in your Linux terminal:

$sudo gem install asciidoctor

Text formatting

Type the following content in the text editor and save the file as favs.asc:

= My Favourite Books

The Scarlet Pimpernel
The Count of Monte Cristo
The Christmas Carol
The Tale of Two Cities

Now open your terminal and issue the command:

$asciidoctor favs.asc

Then return to the current working directory, where you will find an HTML file with the same name as your Asciidoctor file, which you need to open in your browser.

You will find all the book names in one single line, one after the other, but the output would be a little bit more readable if each name was in a single line. To do this, add the ‘+’ at the end of each book name as follows:

The Scarlet Pimpernel +
The Count of Monte Cristo +
The Christmas Carol +
The Tale of Two Cities +

The above code will add line breaks after the ‘+’, so that each book name is displayed in a single line. Now, let us look at some of the basic text formatting options that are often used in your documents.

Text can be made bold by adding an ‘*’ (asterix) character at both ends of the word, as follows:

*The Scarlet Pimpernel*

Or you can italicise a word by using the ‘_’ (underscore) character wrapped around the word, as shown below:

_The Scarlet Pimpernel_

These rules can be applied to a single character also. If you want to apply a monospace font style to a particular piece of text, you can use the ‘`’ character, as follows:

`The Scarlet Pimpernel`

Or you can use multiple styles for a single word or line, as shown below:

The **Adventure** _of_ **_``D``ancing_** `**M**en`

To highlight text, enclose the text using ‘#’, as shown below:

The Secret #Adversary#

There are cases when you want specific words to be in a smaller font. To achieve this effect, add the [small] attribute followed by the ‘#’ enclosing the word as shown below:

Mary had a [small]#little# lamb

In the same way, you can add a word in a bigger font, as follows:

That Polar bear is [big]##huge##

The outputs for the above code snippets are displayed in Figure 1.

Tables

Tables in Asciidoctor have a simple syntax, but offer sophisticated features.
Let’s start with the simple example of how to define tables in Asciidoctor:

|===
|Alexander Dumas|Charles Dickens
|Agatha Christie|George Orwell
|Sir Arthur Conan Doyle|Wilkie Collins
|===

The vertical bar with three equal signs (|===) is used to define the boundaries of a table. The default table data format in Asciidoctor is PSV (pipe separated values). Data is displayed in cells, and each cell is created in Asciidoctor as soon as a vertical bar (|) is encountered in the code.

Each row shares the same number of cells. If any vertical bar is detected without any data next to it, it will create an empty cell in your table.

cols attribute: When you are creating the cells of a row individually on a consecutive line, you will need to use the cols attribute to specify the number of columns for the table, as shown below:

[cols=”3*”]
|===
|Debian
|Fedora
|RedHat
|Open Suse
|Linux Mint
|Apricity
|===

Please note that if you prefer to avoid the cols attribute in your table, your table will be rendered in the number of columns with respect to the number of cells right after the character (|===).

Column alignment: You can align the column content as left, right or centre. In the following code, you can use a different alignment for each column in the table, or you can align all the columns in the same way.

[cols=”3*”]
[cols=”<,^,>”]
|===
|Debian
|Fedora
|RedHat
|Open Suse
|Linux Mint
|Apricity
|===

In the above code, ‘<’ means left alignment, ‘^’ means centre alignment, and ‘>’ means right alignment.

Column width: Setting the column width is useful— your content doesn’t overlap in the table because of lack of space. The width values range from 1-99.

[cols=”10,20,30”]
|===
|Debian
|Fedora
|RedHat
|Open Suse
|===

Cell duplication: Sometimes, in tables, the same data needs to be replicated in consecutive columns—for example, default values. To duplicate a cell for successive columns, you can use the number along with the ‘*’ as a prefix to ‘|’.

|===
|London |Sydney |Hamburg
3*|Stockholm
|Nairobi |Prague |Budapest
|===

Importing from external sources: Asciidoctor can import CSV and DSV datasets to your tables using the include directive, as follows:

[format=”csv”, options=”header”]
|===
include::movie.csv[]
|===

The first line of the code states the format of the dataset that will be used in this table and adds the header for the table.

Lists
Asciidoctor supports both ordered and unordered lists. The syntax for declaring them looks similar, except for one tiny character. For unordered lists, you need to use ‘*’, as shown below:

* Alexander Dumas
* Baroness Orcy
* Sir Arthur Conan Doyle
* George Orwell

If you wish to have square bullets for your lists, modify the code as shown below:

[square]
* Alexander Dumas
* Baroness Orcy
* Sir Arthur Conan Doyle
* George Orwell

For ordered lists, you can use ‘.’ in front of the items you wish to place in a list, as follows:

.My Favorite Authors
. Frederick Forsyth
. Dan Brown
. Steve Berry
. Scott Mariani

It is important to notice that, in the first line, there’s no space between the period and the title of the list. Also, there’s a space given between the period and the list items.

If you wish to reverse the list, just add [%reversed] at the top of the list declaration, as shown below:

[%reversed]
.My Favourite Authors
. Frederick Forsyth
. Dan Brown
. Steve Berry
. Scott Mariani

Images, video and audio

Image: An image is worth a thousand words. People find documents that contain only text unattractive and boring. Inserting images in your document could spice up the overall content.

.Duck Duck Go Search Engine Logo
image::duck-duck-go-logo.png[200,200]

The first line of the code adds a caption for the image, the second line inserts the image file duck-duck-go-logo.png, and the numbers in the brackets show the specified width and height of the image instead of its original size.

When you want to keep your images in a separate folder, you may use the :imagesdir: attribute. It will require an absolute path of that particular folder. You can save all the images in this folder to avoid them getting mixed up with other documents.

:imagesdir: /home/admin/Downloads/
image::Mozilla_Foundation_logo.svg.png[200,200]

The first line tells Asciidoctor where to look for the images. In our case, it is Downloads. The next line inserts the image Mozilla_Foundation_logo.svg.png from the Downloads folder.

If you want to use an image from the Web, just add the file URL for the particular image, followed by brackets; it has the alternative text, width and height of the image.

image::https://upload.wikimedia.org/wikipedia/commons/d/db/
Elementary_logo.svg[ Elementary _OS,200,200]

Video and audio: Videos can be inserted in two ways. We can either use video from a video streaming site (YouTube or Vimeo) or you can add the video file from local storage:

.Creative Commons Video
video::sPuSg53RFb0[youtube]

The above line embeds a video from YouTube. The contents of the brackets show the name of the video streaming site. It is recommended that you use video files from the streaming sites since they provide an optimised version of the file, depending on the network, hardware and browser capabilities of your system.

Audio files can be included in the same way as video files, as shown below:

audio::yousetmefree.mp3[]

Other useful features

Apart from what’s mentioned above, Asciidoctor also offers some awesome features that can be used for fine tuning your content.

Admonition blocks: Writers use admonition blocks in their documentation in order to highlight the information. The most common admonition types are important, tip, warning, caution and note. In Asciidoctor, we can use them as follows:

:icons: font
[TIP]
This is a local site without Online connections on the Internet.
[CAUTION]
Cautionary Message
[WARNING]
Please read carefully, this is a Warning message
[NOTE]
This is the site for you!!!
[IMPORTANT]
This could be important

The first line of the code is optional, it instructs the asciidoctor to add icons instead of words to display the admonition blocks in your document.

Textual replacements: We can use textual replacement symbols such as copyright, registered and trade mark in the content, as shown below:

(C) - Copyright
(R) - Registered
(TM) – Trademark

Footnotes: Footnotes are special comments, references or additional information, which are usually placed at the bottom of the page. Each footnote is designated for particular elements in the text in Asciidoctor. Footnotes can be placed by using the footnote: [] macro.

This is an example of Footnote footnote: [this is the actual footnote, not the other]

Converting to PDF: So far, we have seen our output in HTML format, but what if you need your content in PDF format. To do that, install the Asciidoctor-pdf gem:

$ sudo gem install asciidoctor-pdf –pre

Once the gem is installed, choose the document that you wish to convert to PDF and type the following command in your terminal:

$asciidoctor-pdf article.asc

You will find a PDF file in your present working directory with the same name as your Asciidoctor file.