I have to say, that I already use Markdown to write everything : documentation, notes, blog posts, specifications.
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
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.
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 “=”.
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
This *_text_* as the words *_text_* bold and italic.
Note : Markdown has the same syntax to mark text bold and italic.
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 :
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 :
This automatically color the syntax.
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 :
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.
This is something missing in Markdown, so to me it’s a big advantage for AsciiDoc.
Here is a simple table :
|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 = “|“ :
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
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 :
Simple and effective no ?
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 |=== ====
The only brake I see, is that i think the syntax will be difficult to learn for a non technical writers.
So, I really think I will migrate to AsciiDoc in the near future.