Markdown vs Asciidoctor

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 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).

Heh, having typed this all out, I realized that I probably could’ve just linked Consider Using Asciidoctor for Your Next Presentation

2 Likes

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

1 Like

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.

1 Like

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 :slight_smile:

Take links:

In markdown, we have [Link](http://a.com) for plain links and ![Image](http://url/a.png) 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.

Hosted by Flying Circus.