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