News for hackers. Stuff that matters.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by jszymborski on Friday November 04, 2022 @01:59PM (#33471129)
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.

Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by e12e on Friday November 04, 2022 @02:38PM (#33471658)
I thought the answer always was "pandoc" when the question was (un)structured markup...
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by kevin_thibedeau on Friday November 04, 2022 @06:25PM (#33474774)
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.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by Tomte on Friday November 04, 2022 @02:04PM (#33471222)
Maybe a solution: AsciidoctorJ is an official JVM port (using JRuby). You just get the jar file and execute it.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by geokon on Friday November 04, 2022 @02:09PM (#33471315)
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
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by innocentoldguy on Friday November 04, 2022 @02:57PM (#33471925)
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
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by pbronez on Friday November 04, 2022 @03:25PM (#33472356)
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.

Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by sofixa on Friday November 04, 2022 @06:15PM (#33474655)
Hugo (a great static site generator) supports Asciidoc, but it needs Asciidoc for the parsing.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by darekkay on Saturday November 05, 2022 @02:23AM (#33478515)
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.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by bobbylarrybobby on Monday November 07, 2022 @11:40PM (#33515924)
Surprised to hear that Asciidoctor tooling is challenging. If you're ok going extension-less, then something akin to `brew install asciidoctor` is enough.