AsciiDoc & AsciiDoctor first step and first thoughts

Yesterday I was at Devoxx France and I’ve seen a talk about AsciiDoc (and AsciiDoctor).

I have to say, that I already use Markdown to write everything : documentation, notes, blog posts, specifications.

During the talk, Dan Allen, one of the speaker insisted on the tooling around AsciiDoctor.

Actually I already thoughts it was one of the major problem with Markdown.

So I decided to try AsciiDoc for writing this article !

Basic Syntax appropriation

Like in Markdown, syntax is quite simple to appropriate, at least for the basics.

If you are used to takes notes with a computer in a plain text file, you may already use some AsciiDoc.

Paragraphs are lines

For example, to create some text paragraphs, we only have to separate lines of text by a blank line.

This line represent a paragraph.

And this line is another paragraph.

Note : Markdown has the same syntax to create paragraphs

List items

The basic way to create a list item, is to use a "-" or a "*" for each item, something like that :

* First
* Second
  - Sub one
  - Sub two
* Third

Note : Markdown has the same syntax to create lists.

Titles

In order to create sections in your document, you may want to create sections titles. This is very simple, for a main title, simply start the line with an equal (`"=") symbol.

And for a first level title, use two equals :==, and for a 6th level title use : ======

= 1. Title (H1 (level 0) )

== 1.1 Title 2 (H2 (level 1)

=== 1.1.1 Title 3 (H3)

Note : In Markdown the principle is similar, but you will have to use a “#” character instead of “=”.

Styling text.

Other things you may want to do is to emphasis some text by adding some italic or bold (or both) styling.

In order to make some text bold, you only have to surround the text with a "*" and for italic you have to surround the text with "_".

This *text* as the words *text* bold.

This _text_ as the words _text_ italic.

To create some text both italic & bold , you can combine "*" and "_".

This *_text_* as the words *_text_* bold and italic.

Note : Markdown has the same syntax to mark text bold and italic.

Code

As I write a lot of documentation for developers, many of my articles and documents includes some code.

As the documentation says, you only have to create a block, with four dashes (`"–—-“) before and after the code you write :

----
(function(){
  // Javascript code auto call function
})()
----

Note : In Markdown you have to use three grave accent ("`") to create a code section.

In AsciiDoc, you can also tell what is the language of the code :

[source, javascript]
----
(function(){
  // Javascript code auto call function
})()
----

This automatically color the syntax.

Links

One thing you may want to add in your documents are links.

To add a link to the AsciiDoc web site, you just have to add the url in your text :

http://www.asciidoc.org

To create a link with a specific text you have write the text in “[“ and “]“ :

http://www.asciidoc.org[AsciiDoc Web Site]

Note : You can create links between AsciiDoc documents and between sections in a document.

More Advanced usage

Markdown is a very simple syntax but it has limitations, for example the initial definition does not include the ability of creating tables, including other (Markdown) files, or adding your own syntax sugar.

INFO : Markdown can be extended with flavors (like the Github Flavor) but renders do not supports all the flavors.

Ok, so let’s have a look at some other capabilities of AsciiDoc.

Creating Tables

This is something missing in Markdown, so to me it’s a big advantage for AsciiDoc.

Here is a simple table :

id title author
1 Secrets of the javascript ninja John Resig
2 Specification By Example Gojko Adzic

To create the above table you have to think about the structure of the table, but first to start a table you have to write this : “|===“, use the same code to mark the end of the table. So to create a table you need at least the following :

|===

|===

Then the table has 3 rows, first row is the table header, then there is two rows of datas.

The first row (the header) will define number of columns, let see how to create this row :

|===
| id | title | author

|===

Then the other rows can be written on multiple lines, each cell must start with a pipe = “|“ :

|===
| id | title | author

| 1
| Secrets of the javascript ninja
| John Resig

| 2
| Specification By Example
| Gojko Adzic

|===

Note : Each rows are separated by a blank line

This is the simplest way to create a table in AsciiDoc, but you can create very complicated tables (ie: with rowspan and colspan). Please refer to the documentation to see how to create an advanced table

Include documents

This feature of AsciiDoc is one of the feature i would like to have in Like in Markdown.

This allow you to add a document on another document.

In order to add a document “footer.adoc“ in the current document you only need to add the following line :

include::footer.adoc[]

Simple and effective no ?

Specials Paragraphs

AsciiDoc comes with a bunch of special paragraph they are Admonition paragraph.

The best example are all the “NOTE” blocks in this document.

All those paragraphs are :

Example from the Documentation

NOTE: An admonition paragraph draws the reader's attention to
auxiliary information.
Its purpose is determined by the label
at the beginning of the paragraph.

Here are the other built-in admonition types:

TIP: Pro tip...

IMPORTANT: Don't forget...

WARNING: Watch out for...

CAUTION: Ensure that...

You can also create larger block of Admonition like that :

[NOTE]
====
This Will allow you to create a block with lists :

 * list 1
 * list 2
 * list 3

And maybe a table

|===
| Product | Author

| jQuery
| John Resig

| Linux
| Linus Torvald
|===
====

Conclusion

In the introduction I said that I am used to write documents in Markdown syntax, but for this article i forced myself to use AsciiDoc.

The only brake I see, is that i think the syntax will be difficult to learn for a non technical writers.

But I have to say that first approach is easier than I thought, and AsciiDoc has a lot of feature very useful that are not implemented by default in Markdown.

So, I really think I will migrate to AsciiDoc in the near future.