undefined | Better HN

0 pointsgouggoug3y ago0 comments

> AsciiDoc's flagship feature is the include directive (think partials). GitHub rendering doesn't support it. On GitLab you are limited to ~30 includes, after which your document just spits out source. So in most cases, you can't preview AsciiDoc files that use the include directive without cloning the repo and previewing it locally.

Does Markdown support partials/includes, and does Github honor them? I don't believe it does... (I tried googling about it, didn't find anything, but I could be wrong) so not sure how this can be used as an argument against asciidoc.

> When you take away the include directive you have a less elegant syntax that is harder for contributors to read, much less adopt.

Markdown and AsciiDoc syntax are extremely [0]similar, and AsciiDoc supports markdown's syntax.

[0]: https://asciidoc.org/#compare

0 comments

1 comments · 1 top-level

subpixel3y ago

I've used both for a decade or more, and my opinion is that includes/partials is the only thing AsciiDoc offers that even justifies considering it as a markup language for docs. If (big if!) using includes/partials without React is so important you'd consider giving up all the benefits of Markdown.

IBM, Microsoft and Stripe all have tooling that enables Markdown includes/partials. None of those will render natively in GitHub or Gitlab - but if you really need that feature you probably don't care as the AsciiDoc support is also so poor.

I think if AsciiDoc and Markdown were in the same league from a writing and reading perspective, AsciiDoc might have more traction. Other comments in this thread support the case that it's just harder to write and read as markup.

A whole other topic is how Markdown has been adopted by React-driven systems. This just solidifies Markdown's position as the lingua franca.

j / k navigate · click thread line to collapse