Hacker News Reader

AsciiDoc is compatible with Markdown and can generate many output formats, including Docbook and Latex, which enables toolchain reuse. This provides more optionality than RST.

The most important property of documentation is existence. Markdown has a low barrier to entry and the markup can later be upgraded to Asciidoc.

View on HN

This is not the only comment ITT to recommend Asciidoc. It seems interesting, so I looked into it. On the asciidoc Github page [0], I found this note: "NOTE: This implementation is written in Python 2, which EOLs in Jan 2020. AsciiDoc development is being continued under @asciidoctor."

In other words, upgrading to py3 was such a pain, they rewrote it in Ruby instead. Ouch! This has got to be the worst example (among more than a few) of py3 pain I've seen yet!

[0] https://github.com/asciidoc/asciidoc

The Ruby implementation (Asciidoctor) is a separate implementation by a different team. I recommend to use it together with Antora (Asciidoc's answer to Sphinx).

Sure, that seemed likely. The python repo seems pretty unambiguously deprecated, however.

Except that the version most distributions that are ridding themselves of python2 are using is a new python3 ported version. As far as I know the maintainer of that repository isn't touching it anymore, which is why it isn't linked. https://asciidoc3.org/

Reply on news.ycombinator.com