Is there an official file extension for standalone Markdown files?
2
7 Answers
There is no requirement for a Markdown file extension. However to ensure editors or parsers recognise a file is Markdown-formatted, one of the following extensions would be checked for:
.md
.mkd
.mdwn
.mdown
.mdtxt
.mdtext
.markdown
.text
There are websites such as GitHub that use subset of these extensions when converting to HTML so developers will conform to their standard.
Examples of extension usage:
GitHub: .markdown, .mdown, .mkdn, .mkd, .mdwn, .md (source)
Vim markdown: .markdown, .mdown, .mkdn, .mdwn, .mkd, .md (vim-m-src)
Bitbucket: .md, .mkd, .mkdn, .mdown, .markdown, .text (source)
Further Reading
The Markdown mailing list has interesting discussions about this topic: 1, 2, such as this snippet:
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.
-
Bitbucket uses md, mkdn, markdown: confluence.atlassian.com/display/BITBUCKET/… Commented Jan 4, 2012 at 0:39
-
1.md and .markdown appear to be the most common extensions in use at this point. Commented Aug 2, 2017 at 20:08
-
1Little update on the extensions recognized by GitHub, it seems the list grew a bit:
md,mkd,mkdn,mdwn,mdown,markdown– source Commented Jan 27, 2019 at 10:04 -
The idea of MarkDown and similar light-weight markups is to be readable as plain text, thus they have text/plain extension (.txt or .text).
However, there are some people who use .markdown or .mdown.
-
2Just for the record, Elements for the iPhone recognizes .md, .markdown, .mdown, .mdwn and .text Commented Feb 26, 2011 at 10:31
-
4vim 7.3 recognizes .markdown and .mdown, so .markdown is the most descriptive one. Commented May 19, 2011 at 11:19
-
1
-
3I've seen a couple of .md in GitHub too, and my Vim at the office recognizes it as Markdown (I've to check why it doesn't at home).– WernightCommented Jul 27, 2011 at 6:17
-
1This answer is not as extensive / complete as the one with the most votes. Commented Aug 25, 2011 at 12:01
iA Writer uses the extension .md for Markdown content.
Doxygen added Markdown support in v1.8. It looks for .md or .markdown file extensions.
I'm not aware of one, but I think a precedent is set by the use of the .text extension on the official website to reveal the Markdown that produces the pages.
answered Feb 23, 2011 at 16:58
-
3Just because the official website uses it doesn't mean it's a good idea, though.
.textmeans plain text, not markdown.– endolithCommented May 22, 2012 at 19:36 -
@endolith "not markdown": 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. Commented Jul 5, 2022 at 11:06
In short, the answer is no.
If you are simply using markdown files as stand-alone files that will not be processed in any way, name them however you please. If you are using them in a system the processes them into HTML or PDF or some other format, then you need to figure out what file extensions that system expects for markdown files.
Also, in the context of a UNIX system, file extensions are not even mandatory. You could simply have a file called "README" in markdown format.
answered May 19, 2011 at 19:51
-
But
filewill only tell you that it is ASCII text, which does not tell me that I can run it throughmarkdown. Commented Jun 8, 2011 at 19:21
Hmm... Geany, the open source IDE, when saving a Markdown formatted file, uses the .mdml extension. Strange that it seems to be the only one...
filename.md.txtin the same way asfilename.rst.txt? It indicates that it's markdown format, but also falls back to plain text if you don't have something to handle markdown. GitHub recognizes.rst.txt, but not.md.txt: gist.github.com/2770487.mdand.mkdthe only commonly used options. Of those.mdis FAR more popular so I highly suggest using that. Don't worry about machine descriptor files; they aren't that widely used and they should be perfectly editable in a Markdown Editor (just ignore the preview portion of the editor).