Why You Shouldn't Use Markdown for Documentation(ericholscher.com)
I’d like to lay out the main arguments that I have against Markdown. Hopefully this will be useful in helping you decide whether it’s a good fit for your organization. If you are considering Markdown, I hope that you also look at Asciidoctor and Sphinx. I find them to be much better toolsets for writing documentation.