AsciiDoc is a pretty nice plaintext format with a rich offer of components.
I wish it was more widely supported. Unfortunately, the only worthy implementation is in Ruby (AsciiDoctor), which is what all the other projects (in Java, Python) use.
AsciiDoc would see more adoption, I think, if independent implementations existed in other languages.
I successfully used AsciiDoc and AsciiDoctor to write 2 books [0].
I found it better suit for long form content than, say, markdown, due to the fact it has more language grammar for things like chapter, admonitions, etc.
AsciiDoc is a feature-rich markup language. It's great. But I have two complaints:
1. Its readability is not very good. There is too much non-content text for me.
2. The grammar set is not small and natural.
I prefer Asciidoc over markdown for documents where chapters, cross references, call outs, etc are valuable. For things that one might want to turn into a PDF.
The tooling is a bit of a pain, but the Java world has pretty good integration (gradle, intellij)
I switched from pandoc markdown to asciidoc for writing technical blog posts, but switched back after a year due to the fact that pandoc is easier to setup and tweak with plugins
Is there by any chance some variant of Jupyter that supports asciidoc for the text formatting? If so, how difficult would it be to replace Jupyter's marked.js renderer with asciidoctor?
Still doesn't support footnotes (only as endnotes): https://docs.asciidoctor.org/asciidoc/latest/macros/footnote...
Very underappreciated project, for multiple repo online docs there's https://antora.org it is built on Asciidoctor.js, a powerful tool but the learning curve can be steep.
Better than Markdown, but I have trouble with muscle memory and the ubiquity of Markdown. One of these days I'll switch. It's similar to the QWERTY/Dvorak problem.
I did my entire MLaw (in Switzerland) with asciidoctor, so I have a lot of respect for it.
(except the master's thesis, which I did with latex)
I’ve in recent years started to favor reStructuredText over AsciiDoc for three reasons. 1) Docutils’s output in like 95% good, semantic HTML where Asciidoctor has a lot of issues (I would note that non-Docutils is often bad, second-class & reliant on what Markdown outputs for ‘compatibility’ (meaning less features for you)) 2) the features difference between the two I prefer the rST set (such as abbreviations) 3) the spec seems so complicated Pandoc can’t realistically have a reader, just a writer & pretty much the Ruby-based Asciidoctor application ends up being the AsciiDoc specification.
That said, I would choose AsciiDoc every single day without hesitation over Markdown the minute you are talking about documentation or any sort of technical writing since Markdown is far too feature poor & buying into one specific fork is locking you into incompatibility & other headaches/compromises.