File extension for Markdown files?

117

Is there an official file extension for standalone Markdown files?

Beat Rupp

Posted 2011-02-23T16:23:18.717

Reputation: 1 301

2If you plan on storing these files on a Windows machine then I'd stick with an <= 3 character extension. This makes .md and .mkd the only commonly used options. Of those .md is 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). – krowe2 – 2014-10-27T20:24:05.897

Does anyone use filename.md.txt in the same way as filename.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: https://gist.github.com/2770487

– endolith – 2012-05-22T17:44:03.513

Answers

110

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.

Cas

Posted 2011-02-23T16:23:18.717

Reputation: 1 600

.md and .markdown appear to be the most common extensions in use at this point. – Christopher Barber – 2017-08-02T20:08:43.263

Little update on the extensions recognized by GitHub, it seems the list grew a bit: md, mkd, mkdn, mdwn, mdown, markdown – source

– Robert Audi – 2019-01-27T10:04:07.687

Bitbucket uses md, mkdn, markdown: http://confluence.atlassian.com/display/BITBUCKET/Displaying+README+Text+on+the+Overview

– Randy Syring – 2012-01-04T00:39:44.883

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.

vartec

Posted 2011-02-23T16:23:18.717

Reputation: 740

1Markdown is human readable but unlike plain text has specific rules describing how it is to be rendered in HTML. Even with the wide variation in existing Markdown implementations it clearly does merit its own file extension. – Christopher Barber – 2017-08-02T20:04:02.667

2Just for the record, Elements for the iPhone recognizes .md, .markdown, .mdown, .mdwn and .text – Beat Rupp – 2011-02-26T10:31:24.810

4vim 7.3 recognizes .markdown and .mdown, so .markdown is the most descriptive one. – Martin Ueding – 2011-05-19T11:19:30.970

textmate likes many, including .markdown – bentford – 2011-05-21T02:02:41.650

1Kohana uses .md – Liam Dawson – 2011-07-24T11:33:28.887

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). – Wernight – 2011-07-27T06:17:41.837

1This answer is not as extensive / complete as the one with the most votes. – svandragt – 2011-08-25T12:01:42.267

@Wernight: The default vim configuration only recognizes README.md as Markdown, not an arbitrary file with the .md extension.

– Snowball – 2012-10-14T13:05:43.540

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.

Paused until further notice.

Posted 2011-02-23T16:23:18.717

Reputation: 86 075

3Just because the official website uses it doesn't mean it's a good idea, though. .text means plain text, not markdown. – endolith – 2012-05-22T19:36:18.053

iA Writer uses the extension .md for Markdown content.

Subhash Chandran

Posted 2011-02-23T16:23:18.717

Reputation: 21

Doxygen added Markdown support in v1.8. It looks for .md or .markdown file extensions.

Andy Dent

Posted 2011-02-23T16:23:18.717

Reputation: 271

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.

Ryan C. Thompson

Posted 2011-02-23T16:23:18.717

Reputation: 10 085

But file will only tell you that it is ASCII text, which does not tell me that I can run it through markdown. – Martin Ueding – 2011-06-08T19:21:34.347

As an addition to Cas' very good answer I'd like to mention that his link to the github repository of Vim markdown is somewhat deprecated.

The user plasticboy was the original creator of Vim Markdown but it is currently developed and uploaded to the vim scripts site by Hallison Batista and others.

For example one user did a fork to support Gollum links.

LeoR

Posted 2011-02-23T16:23:18.717

Reputation: 111

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...

User203040

Posted 2011-02-23T16:23:18.717

Reputation: 1