Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

dewanahmed.com

Post reply on HN
Print view View original

11–20 of 89 posts

Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

#11

Post by ilyt »

keybored wrote: post #3

Points to the Markdown family for using mostly nice syntax. I mean the basics like lists, links, and headings look fine (I can do without the underlined headings or whatever they are called though). Markdown is nice for readmes and simple notes. Usage beyond that is not quite questionable to but debatable. Asciidoc seems to have a solid backend. But it seems to have a problem with nesting. Nesting things should be ta…

Markdown have a bit of fragmentation problem. CommonMark and Github variant have been nice steps forward, but for code I'd like to have some more extensions rolled in as another standard. For code docs in particular ability to just embed text diagrams would be great, you can hack around that with PlantUML but then you need to have stuff that supports it...

Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

#12

Post by NoThisIsMe »

keybored wrote: post #3

Points to the Markdown family for using mostly nice syntax. I mean the basics like lists, links, and headings look fine (I can do without the underlined headings or whatever they are called though). Markdown is nice for readmes and simple notes. Usage beyond that is not quite questionable to but debatable. Asciidoc seems to have a solid backend. But it seems to have a problem with nesting. Nesting things should be ta…

What is "regular markup"?

Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

#13

Post by 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.

Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

#14

Post by kzrdude »

LukeShu wrote: post #4
keybored wrote: post #3

Points to the Markdown family for using mostly nice syntax. I mean the basics like lists, links, and headings look fine (I can do without the underlined headings or whatever they are called though). Markdown is nice for readmes and simple notes. Usage beyond that is not quite questionable to but debatable. Asciidoc seems to have a solid backend. But it seems to have a problem with nesting. Nesting things should be ta…

For a long time reStructuredText was "the Python thing", the way POD is "the Perl thing", where it's the "only" choice in that ecosystem, but you didn't really see it outside of that ecosystem. But nowadays (thanks to Sphinx?) reStructuredText is also used for big systems-y projects, including the Linux kernel docs and Envoy proxy.

rST is nice for making complete documents, but for smaller things it just is not practical. For one-off things (like github comments) or smaller wikis, markdown is just more practical. rST has bigger reliance on a mildly smart editor than markdown has, just to handle indentation.

The upside of rST is that it's just more complete, it has more document elements available. Markdown is often written without thought to having a readable plain text document, but rST is often very readable in plain text too.

Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

#15

Post by fluidcruft »

mooreds wrote: post #2

As I said on Twitter, this was a great article, but needs to mention Jekyll, which was one of the OG static site generators. There are others such as eleventy as well. I was kinda shocked that asciidoc came up as the recommended documentation solution; we use it and were looking to possibly make a move because of some of the warts (includes are great, but then make updating doc more complex, no one line ifdef check,…

Two things on my radar to check out are MyST markdown and quarto.

Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

#16

Post by Tomte »

jszymborski wrote: post #13

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.

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-as-code

#17

Post by IshKebab »

deathanatos wrote: post #6

The "insanity" of the section characters isn't really … it's just that the adorning character doesn't matter so much. (Other than it has to be the same.) The picture-of-a-tweet nails it, but the author misses the point. It's not "we have Python devs" it's "reST has the best syntax for extensibility": if you need to start doing some sort of macro or pre-processing, reST's syntax is cut out for that. M↓ is not; you'll…

My experience of Docutils is that it is a half finished undocumented mess. It doesn't really matter how good RST's syntax is.

Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

#18

Post by geokon »

Tomte wrote: post #16
jszymborski wrote: post #13

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.

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

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-as-code

#19

Post by e12e »

jszymborski wrote: post #13

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.

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