From my (limited) experience of writing a documentation page for a library I made, Markdown is pretty limited (speaking of CommonMark here). Even basic things like table or image need HTML to be done. The gain in syntax is lost on the coherence side as the document mixes two languages, and an additional step of processing the document is required to transform it in full HTML.
It have it use cases but writing long and complex documents is not one of them.