RestructuredText (usually used within Sphinx) is the only alternative in the same class. Unfortunately there are hardly any comparisons. Maybe there are no people who have significant experience with both.
I reckon reStructuredText is the best syntactic and semantic foundation of all the ones I’ve seen, but there are a few things it could do with changing. Most significantly, reStructuredText is designed for being written in a sane text editor, where indenting stuff is easy; but this doesn’t work well for use in a plain <textarea> as web applications of it will commonly go for, where any indentation must be applied manually by the writer. So I’d say it’d be good to get a new syntax construct for fenced, rather than indented, directives. For example, this is what reStructuredText has:
.. directive-name:: first-line-options
:subsequent-options: and their values
:and-more: if you want
Then the directive’s body.
And here’s a strawman fenced syntax:
```directive-name:: first-line-options
:subsequent-options: and their values
:and-more: if you want
Then the directive’s body.
```
Of course, once you’re touching something like that you’d want to touch more things to make it all consistent again, but it’d all be perfectly possible. (Would you use backtick? Dunno. I hear it’s hard to access on some keyboard layouts like German.)
As it stands, reStructuredText is based around having visually-pretty source: monospacedly-aligned tables, indentation for hierarchy, that sort of thing. (Headings feel like the only major thing that doesn’t use very significant whitespace.) I almost always like this, but there are definitely some situations when it’d be nice not to work that way.
Would you go all-in on fenced things rather than indented things? I dunno. Probably.
I think it would easier to build a website with a more feature-rich <textarea> alternative, than it would be to push that clunky syntax onto end-users.
reStructuredText and AsciiDoc are already straddling the line between Markdown and full-featured markup languages. If you need more than this, then you should probably bite the bullet and just use LaTeX or some other markup.
> I think it would easier to build a website with a more feature-rich <textarea> alternative, than it would be to push that clunky syntax onto end-users.
The <textarea> we always have with us. Anything extensively indentation-based is doomed as a general-purpose web markup language (where you’re typing in that markup language—WYSIWYG/WYSIWYM editors are another matter), because all <textarea> “enhancements” will behave differently and will be at least a little painful.
> reStructuredText and AsciiDoc are already straddling the line between Markdown and full-featured markup languages.
I think that’s the wrong framing. All three have roughly the same goals, just Markdown is… worse. And yeah, I’m going to stick with that. Markdown is a low-quality hack that unfortunately (in my mind) gained popularity, a textbook case of “worse is better”, because its dodgy HTML foundation and simple processing model made it far easier to adopt (with many painful incompatibilities between implementations) than something like reStructuredText which is actually sound but takes a lot more effort to implement, so that there’s really only one implementation of it.
reStructuredText and AsciiDoc are full-featured presentation-agnostic markup languages. Markdown is itself fairly minimally-featured, which works out because it’s tied to HTML, which carries the burden of supporting more extensive functionality (though not very well).
LaTeX is a full-featured presentation-locked markup language. It is not at all suitable as an alternative for the likes of reStructuredText, as reStructuredText is much more flexible on presentation options. With something like Sphinx, you can target HTML, LaTeX, Windows’ old-style help, man pages, and more.
> Would you use backtick? Dunno. I hear it’s hard to access on some keyboard layouts like German.
It's fine, you have to press the key right next to the backspace key plus shift. Not exactly ergonomic, but easy to discover on basically any standard QWERTZ keyboard. I'd definitely like a fenced alternative. I'm okay with indentation-based code, but somehow I really dislike using it in my writing.
rST doesn't support nesting markup (bold and italic? nope. code styling in a link? nope.). It's decent for writing software docs, but not good at all (in my opinion) for writing blog posts or other prose.
Yeah, nesting inline markup is definitely something I’d want to add. Note that code styling in a link is actually possible, just convoluted:
Using |foo|__.
.. |foo| replace:: substitution with the ``replace`` directive
__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
Funny thing is that, from what I recollect of investigating this matter a decade ago, there was never any fundamental objection to nested inline markup in reStructuredText, it just… hasn’t happened.
I think it might be a complicated thing to add cleanly for all possible use-cases in the implementation. I remember, how knots in my head formed, when I thought about implementing nested inline markup in a markdown parser. For example if you have nestings like: A B C b c a (where the upper case letter marks the start and lower case letter the end of a markup)
The main implementation of reStructuredText is a custom parser, which might be a hassle to modify to accomodate all cases of nesting, including duplicate ones like: A B A text b a a.
But perhaps all the difficulty in this stems from making the symbols used for starting an inline markup the same as for ending it. Otherwise it would be trivial to count opening and closing "parentheses".
Aside, I still don't understand why restructuedText never took off. The language is so expressive and well-documented, there are anchored references and tables, you can write you academic papers in it and just generate PDFs from it afterwards. There are so many constructs that Markdown and friends don't have.
I have significant experience with both. I've written complex documentation in RsT (Sphinx) and Markdown (Azure Devops, Jupyter, and RMarkdown).
For basic use cases (sections, lists, text formatting), they're both similar in functionality, but Markdown has the advantage of having lightweight, memorable syntax. I would argue that Markdown's syntax is also aesthetically more pleasing (RsT uses a lot of punctuation).
For advanced use cases however (long docs, with math/code listings, complex cross refs, footnotes, callouts, etc.), RsT feels more powerful out of the box. I'm sure Markdown has extensions that can help it achieve similar functionality, but it almost feels like Markdown wasn't designed for advanced use cases.
To use a very imperfect analogy, Markdown to me feels like Microsoft Word (easy to get started on), whereas RsT feels like LaTeX (very code-centric). Although either can be used for any use case, Markdown seems like the right choice for most web-centric use cases, whereas RsT seems slightly more suitable to complex documentation.
As it stands, reStructuredText is based around having visually-pretty source: monospacedly-aligned tables, indentation for hierarchy, that sort of thing. (Headings feel like the only major thing that doesn’t use very significant whitespace.) I almost always like this, but there are definitely some situations when it’d be nice not to work that way.
Would you go all-in on fenced things rather than indented things? I dunno. Probably.