Asciidoctor: A fast text processor and publishing toolchain | Hacker News Reader

Asciidoctor: A fast text processor and publishing toolchain

asciidoctor.org

52 pointsTomte15 comments

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.

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.

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/

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)

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)

Reply on news.ycombinator.com