[igravious]

I feel like this is the tech comparison equivalent of straw-manning.

Take xrefs for instance. They say that the Markdown is:

   See [Usage](#_usage).

   <h2 id="_usage">Usage</h2> 

and that the AsciiDoc is:

   See <<_usage>>.

   == Usage

I mean, clear win for AsciiDoc, right? So I Google "cross reference" "markdown and get this SO post as the first hit: https://stackoverflow.com/questions/5319754/cross-reference-... – 802 point answer saying to do this:

   Take me to [pookie](#pookie)

   <a name="pookie"></a>

I just switched my blog to Jekyll recently so I checked to see what Jekyll does to section headings under the hood (you most want to turn section headings into anchor points, no?) Turns out it automatically turns `<h2>Usage</h2>` into

   <h2 id="usage">Usage</h2>

So clearly Jekyll does the right thing out of the box. Then all you have to do is:

   See [Usage](#_usage).

somewhere else. What I'm getting at is this. Don't pretend your competitor is lamer than it is when doing comparison tables because it'll disincline people to check you out if they find out you've done that. You should steel-man your competitor and _still_ beat them. FWIW I think that Markdown (and its variants) always try to choose a syntax that aligns with how you'd write idiomatic non-HTML text-only styling. I mean compare the unordered and ordered list examples. Markdown chose right, AsciiDoc chose wrong. Objectively speaking, you'd choose the Markdown way naturally. I grant you, sometimes the choices are a little forced but what are you going to do, eh?

[Symbiote]

> I mean compare the unordered and ordered list examples. Markdown chose right, AsciiDoc chose wrong. Objectively speaking, you'd choose the Markdown way naturally.

In a trivial example, Markdown's syntax looks more natural. It might well be the more appropriate syntax for a short README, which expects to be read as plain text at least as often as rendered to HTML.

In real use, i.e. when editing a non-trivial example, AsciiDoctor's multiple-star/dot syntax makes it easier to keep track of things.

You can also use the Markdown-style indentation instead anyway: https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/#...

[fiddlosopher]

In pandoc's extended Markdown you can just write

    # Usage

    See [Usage].
    

https://pandoc.org/MANUAL.html#extension-implicit_header_ref...

[mogztter]

You can click the "Edit this page" button and submit an improvement.

Having said that, the fact remains that you don't have a standard syntax to add an id on a section title (without using HTML directly).

Jekyll might does the right thing but Jekyll is not Markdown. Does it work elsewhere? If not then your document is not really portable.