Try Asciidoc Instead of Markdown (opens in new tab)

(opensource.com)

20 pointsInocez3y ago8 comments

8 comments

Why? Markdown works fine and is better known, I don't see anything that Asciidoc would do better than Markdown.

There are a number of elements supported by AsciiDoc that aren't available in Markdown[0].

For most writing, Markdown is perfectly sufficient. If you're doing complex stuff, however, AsciiDoc might make expressing your intent more straightforward.

[0]: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...

d1sxeyes3y ago

Thanks, this article does not do a great job of highlighting Asciidoc’s USPs

moistly3y ago

> I don't see anything that Asciidoc would do better than Markdown.

If you don’t see anything, it must be because you have closed your eyes. Asciidoc does a ton of things that Markdown can not.

Complex tables. Admonitions. Generated ToCs. Definition lists. Block image with alt text. Inclusions. Block titles. In-line anchors. Conditional directives. Live code inclusion.

Just all the stuff that’s required to write complete, professional documentation instead of blog posts and readme notes.

d1sxeyes3y ago

I didn’t remember any of that from the article so I went back and checked. Seems that although you’re absolutely right, the article doesn’t give any details whatsoever other than obliquely hinting at it somewhere towards the bottom of the article.

Thanks for the comment, it actually seems quite a bit more interesting now.

orthoxerox3y ago

The biggest benefit of GitHub-flavored Markdown is that it works on GitHub with no additional processing needed.

tomjakubowski3y ago

Guess what? Asiidoc works out of the box there too.

bovermyer3y ago

At this point, I use Markdown for my Zola-powered static site, and straight LaTeX for actual books/PDFs.

j / k navigate · click thread line to collapse

8 comments

d1sxeyes3y ago

Why? Markdown works fine and is better known, I don't see anything that Asciidoc would do better than Markdown.

thomascgalvin3y ago

There are a number of elements supported by AsciiDoc that aren't available in Markdown[0].

For most writing, Markdown is perfectly sufficient. If you're doing complex stuff, however, AsciiDoc might make expressing your intent more straightforward.

[0]: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...

d1sxeyes3y ago

Thanks, this article does not do a great job of highlighting Asciidoc’s USPs

moistly3y ago

> I don't see anything that Asciidoc would do better than Markdown.

If you don’t see anything, it must be because you have closed your eyes. Asciidoc does a ton of things that Markdown can not.

Complex tables. Admonitions. Generated ToCs. Definition lists. Block image with alt text. Inclusions. Block titles. In-line anchors. Conditional directives. Live code inclusion.

Just all the stuff that’s required to write complete, professional documentation instead of blog posts and readme notes.

d1sxeyes3y ago

Thanks for the comment, it actually seems quite a bit more interesting now.

orthoxerox3y ago

The biggest benefit of GitHub-flavored Markdown is that it works on GitHub with no additional processing needed.

tomjakubowski3y ago

Guess what? Asiidoc works out of the box there too.

bovermyer3y ago

At this point, I use Markdown for my Zola-powered static site, and straight LaTeX for actual books/PDFs.

j / k navigate · click thread line to collapse