There is no requirement for a Markdown file extension, as other answers have explained. But in order for editors or parsers to guarantee that the file they are using is Markdown-formatted, they would look for one of the following extensions:
.markdown
.mdown
.mkdn
.md
.mkd
.mdwn
.mdtxt
.mdtext
.text
.Rmd
There are websites such as GitHub that only use a selection of these extensions for converting to HTML so developers will conform to their standard. (see examples below)
Personally, I have seen .markdown and .mdown used the most, and as a Linux user I would avoid using .md as this can also be a machine description file for compiling code with GCC.
Examples of extension usage:
GitHub: markdown, mdown, mkdn, mkd, md (source)
Elements Markdown Editor: markdown, mdown, mdwn, md
Vim markdown: markdown, mdown, mkdn, mdwn, mkd, md
Bitbucket: markdown, mdown, mkdn, mkd, md, text (source)
R Studio: Rmd
Further Reading
There is a Markdown mailing list that has interesting discussions about this topic: 1, 2.
And especially revealing is one of the explanations:
Markdown isn't meant to take over the format of a file, it's a way to subtly add information to the plaintext. Really, the presence of Markdown is metadata, not a file format.
...
No one opening a text file will be confused if they find Markdown syntax, it's pure bonus.
In this sense, it makes sense to use ".text", ".txt", or whatever other plaintext extension is relevant.
...
An editor which knows nothing about Markdown won't care about the metadata and won't be confused by the variety of "non-standard" extensions, but will display and edit the plaintext just fine.
As Daniel Andersson says, a syntax file will get you a long way towards what you want. It's still not the same as a WYSIWYG editor, but headings, bold or italic text and code will look different if you have a proper syntax file set up. Note that there are a few competing Markdown plugins. In addition to the one Daniel mentioned, you might try this one or this one.
But in addition, you could try a plugin for Vim like WriteRoom for Vim. The idea is to make Vim visually distraction free. If you add such a plugin, and make (g)Vim as large as possible, you may get even closer to what you want.
Best Answer
I've solved this.
USE_MDFILE_AS_MAINPAGE
has to be the FILE NAME of the Markdown file you are gonna use, which means, FULL PATH will FAIL. I suppose this is a bug existing in the current Doxygen version, so I reported it as a bug.