3 ms·

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 whi

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. When you take away the include directive you have a less elegant syntax that is harder for contributors to read, much less adopt. Add to that a very small community and a lack of critical tools. Most glaringly, there is no linter for AsciiDoc. AsciiDoc just doesn't have advantages over Markdown (including partials, as Markdoc and other tools used by IBM and Microsoft allow them). Meanwhile Markdown renders everywhere, and it's highly legible as source.

gouggoug 4y ago
> 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 https://asciidoc.org/#compare
- subpixel 4y 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.

gouggoug 4y ago

> 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 https://asciidoc.org/#compare

subpixel 4y 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.