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, provisions for extension in its operations, etc.

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, lists, etc, 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 +