|
I never understood this argument about rST. The syntax for the same MD features in rST is only /marginally/ different, certainly not harder. I use both, depending on the context (which forces me to use one or the other). Most of the time you don't even notice the difference, because both have a really good baseline. However MD falls short for writing technical documentation, which is why pretty much anyone has to dope the "standard" (GH flavored MD, and so on). The syntax for the extensions is not any better than what rST offers. rST generally allows a more human-readable writing style, whereas MD with extensions has a lot of very verbose inline formatting. In fact, rST CAN have a slight edge in my mind as a human readable document if you use the appropriate formatting, whereas MD with extensions is easier for a program to parse. But, I repeat myself, for the same set of MD features, rST is hardly different. If you don't believe this, use pandoc and try to transform a vanilla MD document into rST. Now pick any rST page from sphinx documentation, and move back to MD. Hardly any better. sphinx is often criticized for being "hard to write" or illegible, transferring the blame to rST, but for the same set of formatting MD is not better. sphinx allows a whole slew of extra features which require a lot of annotation, and MD doesn't save the day. What's really annoying if having to switch between the two. We have projects which have a good majority of text documents written in MD and then API references in rST. I hate that. There's constant mismatch. Just pick one :( |