Continuing the discussion from Any consensus on documentation generation tool for nixpkgs manual?:
The negatives of switching would be converting all existing md documentation to asciidoc and limiting ourselves to 2 (or 3) implementations when markdown has a wide selection, much more usage, much better understanding across the maintainer-base
Yeah; to be clear, I do think that markdown is a better choice today overall due to network effects. It’s just that it’s “the best thing”, not “good thing”.
What are the meaningful benefits to AsciiDoc over markdown?
For me, they are:
richer set of build-in constructs. There are
video::, tables, definition lists, ability to mix inline formatting (
``hello **world**``is bold within inline)
ability to attach meta to elements:
[.my-style] paragraph of text.
here, in the html output the
my-styleclass. This allows you to add domain-specific extensions in a well-defined way, instead of introducing extensions on the syntax level
well-defined nesting of the elements. In particular,
--delimits a general block, much like
divin HTML. So asciidoctor allows you to express things like “slide with two columns” directly.
more generally, what asciidoctor gives you is essentially a DOM-tree of the document, with nested nodes and attributes. It’s a very expressive input format for tools which can transform it to various output formats.
More generally, to go from the other direction, Asciidoctor is basically XML – you can author arbitrary tree of attributed nodes. But, unlike HTML, YAML, and various other “treeish” formats, asciidoctor’s concrete syntax is actually convenient to author and is readable in the source form. It’s 90% mardown, and the main surface-level change when going from .md to .adoc is changing the syntax of links (in adoc, url goes first).
Heh, having typed this all out, I realized that I probably could’ve just linked Consider Using Asciidoctor for Your Next Presentation