There are a lot of tools that are used by authors and writers when they write their content. However, some of the tools

• have a steep learning curve
• are expensive
• get hard to maintain especially when there are more assets like images, diagrams and videos
• exporting to other formats suitable for web, ebook might require a lot of work
• documenting software technical documentation gets cumbersome
• hard to maintain and check the changes in a source control system

Enter text-based markups! Recently text-based mark-ups became popular especially among the software technical documentation writers. That includes

• Markdown
• ReStructedText
• Asciidoc

Each one has their own pros and cons, but the beauty of each of them is that they are plain text file with some formatting that enables easy transformation to other formats like HTML, PDF etc. The most popular one is Markdown and the one that has the most features and less quirky is the Asciidoc.

The toolchain that brings power of Asciidoc is Asciidoctor. It parses Asciidoc files and helps in converting them to various formats - HTML5, PDF, DocBook, ePub, man pages etc.

A typical Asciidoc file looks like

= Hello, AsciiDoc!
Doc Writer <doc@example.com>

An introduction to http://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

It gets transformed into HTML as

Hello AsciiDoc!

Doc Writer <doc@example.com>

An introduction to AsciiDoc.

First Section

• item 1
• item 2

It allows code snippets to be embedded that are syntax highlighted too. Following is the Asciidoc block of Java code snippet and how it gets rendered

[source,java]
----
class Java {
    public static void main(String[] args){
        System.out.println("Hello World!")
    }
}
----

class Java {
    public static void main(String[] args){
        System.out.println("Hello World!")
    }
}

It also enables text-based diagramming like Mermaid, Graphviz, BlockDiag etc inside the text so that the output renders as a nice diagram. For example, the following mermaid diagram text within the block gets rendered as the diagram below.

[mermaid]
----
graph LR
A --> B
A --> C
B --> D
C --> D
----

Asciidoctor is powerful in many ways because of the plugins in its ecosystem. The plugins enable transforming the content to different formats including PDF, ePub, Stunning HTML5 based presentations and more. We will talk about the presentations in a subsequent post.

Some of the features that Asciidoctor supports are

• Lists
• Tables
• Videos - Background & Foreground
• Images - Background & Foreground
• Admonitions
• Keyboard Macros
• Custom Styles
• Automatic Table of Contents based on Headings

Many of the features can be activated and customised using attributes

The most important and great feature is the ability to include other asciidoc files. This enables teams to work separately on each of the topics independently and when the final output is generated, Asciidoctor puts them all in the right order.

= Program Documentation

include::topic1.adoc[]
include::topic2.adoc[]
.
.
.
include::topicn.adoc[]

As mentioned earlier, the final output could be a html document, pdf file, epub and much more.

It has many more features than what can be covered in this article. It is more of a publishing toolchain that is simple and easy to use.

Head on to Asciidoctor page for more!

Happy writing!