Hacker News new | ask | show | jobs
by chungy 1230 days ago
It's not accurate to say AsciiDoc only has a single implementation, there is the original AsciiDoc written in Python, and also there is AsciiDoctor written in Ruby. Unfortunately, AsciiDoctor is merely _mostly_ compatible and deliberately opted to not support some features. (And being Ruby, GitHub will use AsciiDoctor to render AsciiDoc files; whether you should conform your documents to this environment depends on what you're doing with them.)

AsciiDoc was written primarily as a way to write DocBook without having to use XML. AsciiDoctor has an alternative goal of writing HTML without having to use HTML. The subtle differences between these goals leads to a lot of "gotchas" if you try to serve both of them at the same time. At least if AsciiDoc is only a consumable in your build system and you deliver the compiled artifacts (be it HTML, PDF, man pages, etc), you can probably be fine enough knowing what your implementation does and does not do.
2 comments
stock_toaster 1230 days ago
> And being Ruby, GitHub will use AsciiDoctor to render AsciiDoc files;

but without support for includes. ;_;

ref: https://github.com/github/markup/issues/1095

link
thayne 1230 days ago
There is also a haskell implementation that can be used with pandoc. I'm not sure how compatible it is.
link