Is the flavor of Markdown used a secret?

[WhatFreshHellIsThis]

I can't find a single reference in any of the docs to what flavor of markdown is supported and what tokens are acceptable.

I thought that would be one of the very first and most critical things documented prominently for this type of project as there is obviously no such thing in markdown as a "standard", CommonMark is the closest thing we have today which unfortunately MKDOCS doesn't appear to support.

There is a help section entitled "Writing your docs" subtitled "How to write and layout your markdown source files."

That is where I would have expected to see some indication of what markdown I can use.

[waylan]

MkDocs uses Python-Markdown for Markdown parsing as is noted in the Markdown configuration documentation. You will also find a list of default extensions included by MkDocs and how to add more and alter the parser. Of course, as its name implies, Python-Markdown is a Markdown parser, not a Commonmark parser (CommonMark is not Markdown).

But yeah, we could do a better job of documenting this. "Writing your Docs" seems like a natural place to find some guidance on that sort of thing. Also, I just noticed that where we do link to Python-Markdown, we use an old, dead link (the updated link is used above). So I've labeled this for a documentation update. Of course, PRs are appreciated.

[WhatFreshHellIsThis]

(CommonMark is not Markdown

@waylan Commonmark is the closest thing we have to a standard by my estimation. I understand if you don't want to implement it, but your statement is utterly confounding.

[waylan]

The creator of Markdown (and the only person who gets to have a say in the matter) has indicated that the only standard are these rules. By its own admission, the Commonmark spec contradicts those rules in various respects. The fact that Commonmark calls itself "Markdown" does not make it "Markdown". IMO, they should stop calling it "Markdown" (which confuses people) and instead be honest and call it a new lightweight markup language 'inspired by Markdown'.