Asciidoctor: A fast text processor and publishing toolchain(asciidoctor.org)
asciidoctor.org
Asciidoctor: A fast text processor and publishing toolchain
https://asciidoctor.org/
11 comments
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 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.
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.
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 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
libasciidoc is a Go library (but not an app, and not feature-complete) for converting AsciiDoc to HTML.
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.
[0] https://yieldcode.blog/post/asciidoc-for-book-writing/
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/
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.
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)
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 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)
(except the master's thesis, which I did with latex)
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.