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 image::, 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 p would have my-style class. 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 div in 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).
Thanks for the reply. I’ll also have a more indepth read of the blog post.
The extensions and differences generally seem sane so I’ll have to look into it more.
It’s used by O’Reilly for some of their books and they have some asciidoc/asciidoctor tooling on their GH O’Reilly Media, Inc. · GitHub and likely more internally
It would be nice to see the state of asciidoc improve. (Slightly related, I liked quite a bit of the org-mode stuff but needing to always use emacs made it a bit of a pain to use even if I do like emacs/doom-emacs.) I just did a bit of searching and found this that’s tangentially related to the nix world
Looks like some of the conversion from markdown to asciidoc could be automated with pandoc
Asciidoctor has DocBook’s set of features with much more complicated syntax – with XML, you need to remember quasi-English phrase related to what you want to achieve × with lightweight markup languages, you need to remember sequence of random punctuation (the various link syntaxes are particularly jarring). Personally, I find the former significantly easier to remember.
Markdown has much more limited set of features so it can afford to be more consistent. Also it is so widely used it has unfair advantage of general familiarity.
Finally, we are not choosing Markdown – the RFC settled on CommonMark with extensions. This will allow us to use the familiar format for 95 % of the writing, while still having access to extra features when we need them.
No disagreement here: spec + implementations availability + widespreadness are quality-of-implementation issues which make markdown a better choice today.
But the rest actually sounds like an asciidoctor sales pitch
Take links:
In markdown, we have [Link](http://a.com) for plain links and  for images, two separate syntaxes. In asciidoctor, you have http://a.com[Link], image:url/a.png[alt text], include:code_sample.rs[] — unified syntax, with keyword to signify which semantic element it is.
Or admonitions:
In markdown, we have to introduce a separate surface syntax to enable this feature, which is extension specific to nix:
::: {.warning}
This is a warning
:::
In asciidoctor, there’s a general facility to attach meta to elements:
[paragraph meta goes here]
This is a warning
so admonition is naturally:
[WARNING]
This is a warning
Although this particular example is unfair to markdown – it’s a docbook thing, which asciidoctor was explicitly designed to support.
