Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by mdaniel on Friday November 04, 2022 @06:39PM
(#33474961)
https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h... is excellent, and one of my major pain points. I usually give up and just use ` when I need to talk about backticking in markdown but that idea is much, much better
but I think https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h... is misguided; AFAIK <!-- commentary --> is legal in markdown and far less likely to surprise someone, both with an abnormal comment character as well as the forced block break
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by uranusjr on Sunday November 13, 2022 @03:28PM
(#33587000)
The “one more backtick” syntax is a very early Markdown feature explicitly mentioned by John Gruber (originally only for inline code, of course). It might even be in the original “spec”, I don’t remember, but it dates way back and is implemented by virtually all half-decent Markdown parsers. It’s one of the least utilised feature, however, so huge kudos for MyST to clearly explain it and raise awareness.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by josephg on Friday November 04, 2022 @10:19PM
(#33477120)
Oh that’s lovely. Does it also support note blocks (like are used to render that page)? And are there implementations in other languages?
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by BiteCode_dev on Saturday November 05, 2022 @05:32AM
(#33479623)
Yes, all admonitions (note, warning, danger) are supported, and worst case scenario, you can fallback on inlined rst if you really miss something.
But so far I never needed to.
> And are there implementations in other languages?
That's the probably the biggest limition for myst: for now it's very new and is only implemented in Python.
I supposed it's a good opportunity to learn rust by creating a parser :)
I'll take the opportunity to do a shameless plug for the amazing "Markedly Structured Text", or MyST, a markdown flavor that is both easy to write like markdown, and expressive like rst.
Basically, if you know markdown, you can write decent MyST already. In fact, any markdown is valid MyST and .md is a valid file extension for MyST.
Once you want more, the syntax offers richer construct, but still easy enough to use.
Check it out: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h...
I wanted to love asciidoc because the format rocks, but it never took off and the tooling is still lacking. MyST piggy back on markdown ecosystem, this is less of a problem.
Also, the devs behind it also have a very good track record at creating a good FOSS ecosystem.