Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
1–10 of 89 posts
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#2As 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, feels a bit aged).
Anyone have any other suggestions we should look at?
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#3Points 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 tablestakes in a markup language.
I don’t know much about RestructuredText (no, I won’t play these silly free-caps games) but it doesn’t look that nice to me for whatever reason. It looks the closest to regular markup to me except they have replaced things like brackets with backticks.
And finally I am glad that I never have to use some Wiki lightweight markup variant with silly syntax like using X numbers of apostrophes for emphasis or whatever.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#4Points 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.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#5Markdown can simply be code - the fenced code blocks are quite enjoyable to work with. RMarkdown is this. Before I learned of RMarkdown I had written something to extract code blocks with filenames that are visible in the rendered page (since hiding it at the end of the first triple backquote codefence isn't great for visibility). I'm currently working on a JavaScript-centered notebook tool (rather than Python centered or R centered as two great ones are). https://github.com/ResourcesCo/macchiato/blob/main/scripts/m... https://github.com/ResourcesCo/notebook
Markdown nested lists could also be used as an alternative to JSON and YAML - they would appear as bullets in a rendered markdown file. I didn't know about this until I started experimenting but inline code blocks can contain backquotes just like fenced code blocks can contain triple backquotes, by wrapping them in a greater number of backquotes.
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#6The "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 need to do it out of band. Or, to put it differently, reST's directives offer extension hooks.
> You’ll need to set up an identity and access management (IAM) service in front of your static website. Unless IAM is your jam, it’s better to avail of a managed service to tackle it.
We throw ours behind Github, I think using https://github.com/oauth2-proxy/oauth2-proxy ; then Github is our IAM.
Honestly, while I think reST has a more cleanly thought out syntax that will allow you to grow the complex use cases docs will inevitably hit … the tooling just isn't as good, IMO. Markdown parsers are prolific … reST … not so much, particularly outside of Python. (And IMO, docutils in Python is not very easy to use if you want fine control over parsing & output. It's there, but just hard to take advantage of.) M↓'s syntax is also somewhat limiting: there's just not a lot it can do. (Admonitions, in particular, are useful in tech docs and missing.) There's always HTML, … but that's just not the same.
(I've no experience w/ AsciiDoc.)
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#7I would say HTML?
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#8Why not all 3 at once: https://scroll.pub/public/blog/indented-heredocs.html
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#9Related recent discussion: Elements Of a Great Markup Language
Re: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code
#10As 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,…
The creator of Pandoc is creating a markup language worth looking at: https://djot.net/