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.
The JavaScript version is an automatic translation of the ruby code and also works great (and of course can be used in a browser context). It is obviously not independent though
As Ruby is very brittle when you move between OS we use jruby with gradle - all plugins included. One day I should make it into a native executable with Graal.
Current workplace maintains a good amount of tech docs written in AsciiDoc that have been written over approx 20 years, that create PDF/ebooks and are published as a searchable online version with Antora. It works pretty well.
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?
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 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)
A shout out to the intellij plugin developer. The Asciidoc plugin has so many nice little Features. E.g. consistent file renames, or paste as screenshot which auto creates a file and embeds it.
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.
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.
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
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.
15 comments
[ 3.8 ms ] story [ 45.7 ms ] threadI 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.
Current workplace maintains a good amount of tech docs written in AsciiDoc that have been written over approx 20 years, that create PDF/ebooks and are published as a searchable online version with Antora. It works pretty well.
The tooling is a bit of a pain, but the Java world has pretty good integration (gradle, intellij)
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 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.
[0] https://yieldcode.blog/post/asciidoc-for-book-writing/
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.
(except the master's thesis, which I did with latex)