On: Markdown, Asciidoc, or reStructuredText – a tale o...

[jszymborski]

I love Asciidoc, but the tooling is pretty crummy. It's not much fun to install and manage asciidoctor if you aren't into the ruby space, and pandoc doesn't take asciidoc as an input.

Its the first I'm hearing of Antora though, so I'll be sure to check that out.

[innocentoldguy → jszymborski]

Antora is pretty nice for large documentation projects. For smaller projects, you may want to try 11ty and the Asciidoctor plugin: https://github.com/saneef/eleventy-plugin-asciidoc

[Tomte → jszymborski]

Maybe a solution: AsciidoctorJ is an official JVM port (using JRuby). You just get the jar file and execute it.

[geokon → Tomte]

You can actually used it interactively from the repl in clojure as well if you need access to the api. I forget why, but it made using the reveal.js output much easier than getting the extension working through the command line

[e12e → jszymborski]

I thought the answer always was "pandoc" when the question was (un)structured markup...

[kevin_thibedeau → e12e]

Pandoc weds you to their particular flavor of Markdown as it's the basis for the internal data representation. All other formats it supports are limited to what its MD can do.

[pbronez → jszymborski]

I agree. Every time I think about picking a markup language, I wind up wanting to use Asciidoc but then getting frustrated by the tooling.

Maybe there's a great static site generator written in GO with strong Asciidoc support??

Antora is new to me as well, will review.

[sofixa → pbronez]

Hugo (a great static site generator) supports Asciidoc, but it needs Asciidoc for the parsing.

[bobbylarrybobby → jszymborski]

Surprised to hear that Asciidoctor tooling is challenging. If you're ok going extension-less, then something akin to `brew install asciidoctor` is enough.

[darekkay → jszymborski]

I've migrated our project documentation from pure asciidoctor to Antora and my team loves it. It took some time to set it up the way we wanted, but the effort was worth it.