Consider using asciidoc for the doc

[chevdor]

Asciidoc is pretty much just like markdown but brings a couple goodies that would make the current doc much easier to maintain:

• support generation of a table of content: just add :toc:at the top
• support include of other asciidoc files (and portion of ~): handy to include the samples if we want to do so

Did you consider it?