I went into this article fully expecting to disagree but I think it makes a valid point. Plain Markdown definitely has issues that cause me to gripe to no end. These however are mostly resolved via extensions. The author argues that Markdown isn't a good choice since it lacks these features without modifying the standard however I don't think extensions are too big of an issue.
If the extensions are part of the build script for processing the documentation then ultimately the user and consuming developers won't notice the difference between this and using another markup language.
Hell one of the documentation pipelines I see quite often is the Doxygen + Breathe + Sphynx pipeline. This handles the markdown and offers most of those extensions mentioned by the author out of the box.
If your documentation pipeline works well and the user can't tell the difference, there's no reason to switch. Markdown works and is more elegant to write in than LaTeX and rST by just about every measure in my eyes.
One last note is that every markup language has it's own special blemishes and issues. LaTeX and rST are very much not immune to this and when it comes down to it, a properly built doc pipeline will cover these up no matter the language.
TL;DR: If Markdown is making your life difficult it's probably not Markdown that's broken, it's probably your documentation pipeline.
If the extensions are part of the build script for processing the documentation then ultimately the user and consuming developers won't notice the difference between this and using another markup language.
Hell one of the documentation pipelines I see quite often is the Doxygen + Breathe + Sphynx pipeline. This handles the markdown and offers most of those extensions mentioned by the author out of the box.
If your documentation pipeline works well and the user can't tell the difference, there's no reason to switch. Markdown works and is more elegant to write in than LaTeX and rST by just about every measure in my eyes.
One last note is that every markup language has it's own special blemishes and issues. LaTeX and rST are very much not immune to this and when it comes down to it, a properly built doc pipeline will cover these up no matter the language.
TL;DR: If Markdown is making your life difficult it's probably not Markdown that's broken, it's probably your documentation pipeline.