It's a classic problem with markdown: it's a minimal markup language, which is ok for comments and super simple documents, but requires extensions for pretty much anything else.

This is why every week you see a new markdown implementation which is just ever-so-slightly different than the other, with every service and tool implementing it's own. I dread markdown, because I know there will be extensions. And the extension syntax doesn't look nice/simple. Syntactically, asciidoc or rst is much more thought-of than any markdown-like syntax I've seen.

This is also the main reason I really discourage markdown for anything but a comment system. Just start with something more complete if you plan on documentation.

I was strongly against md on the documentation for julia for exactly these reasons. Not even one year later, md in julia is already contains extensions which are oh-just-very-similar-to-but-not-quite the others.

Unsurprising. Markdown was supposed to be stupid simple but ended being complicated because people can't resist the temptation to extend things.

No.