The fundamental complaint seems to be that the portable subset of Markdown doesn't allow for extending with new types of blocks. I find this an unconvincing ar

The fundamental complaint seems to be that the portable subset of Markdown doesn't allow for extending with new types of blocks. I find this an unconvincing argument against Markdown per se. It's an argument against writing in the portable subset of Markdown, but why would anyone need to do that in their documentation? It isn't as if specific Markdown implementations are hard to come by, or that there is a context where it would be onerously hard to mandate a specific implementation. Not to say that Markdown's fragmentation isn't a bad thing. It's annoying, especially when you do use different implementations in different pieces of software and you're trying to remember whether this version supports tables, say, and what the syntax might be. > “Markdown” is the most commonly used markup language on the internet. That'll be HTML. :) Not just being facetious. HTML is certainly an option for documentation, albeit not one I'd be totally happy with. > You also can’t migrate Markdown easily to another markup language (Asciidoc or RST), because Pandoc and other conversion tools won’t support your flavor’s extensions. Unless those flavours are Markdown Extra or Github or CommonMark, which pandoc does support. Pandoc also supports adding specific syntax extensions ad-hoc, as noted in its fine documentation. Although, I'd question why this would be an issue in practical terms.