File extension for CommonMark?

Perhaps the spec should make a suggestion for what file extension to use when CommonMark (formerly Standard Markdown) data is saved in a separate file? Obviously, this is irrelevant when the data is merely submitted in an HTML form, or saved in a database object, but there are occasions when it might be saved into a flat file, so there ought to be a suggested extension for this. Markdown itself seems to lack consistency in this area; .md, .markdown, .mdown, and .markdn have been observed.

There’s a Daring Fireball post about this very issue. Gruber writes:

Too late now, I suppose, but the only file extension I would endorse is “.markdown”, for the same reason offered by Hilton Lipschitz:

We no longer live in a 8.3 world, so we should be using the most descriptive file extensions. It’s sad that all our operating systems rely on this stupid convention instead of the better creator code or a metadata model, but great that they now support longer file extensions.

However, file extensions sometimes have to be typed, so a long file extension like .markdown may not be the most appropriate.

I don’t see any reason why .md or even .markdown wouldn’t be fine, since CommonMark is designed to be fully Markdown compatible, and in the cases where the traditional Markdown spec is ambiguous, to choose the most compatible definition that is closest to most authors’ intent.


I suppose we can still say that CommonMark is a Markdown implementation, so we do not need (nor want) a new file extension. .md and .markdown is widely supported by now, so I hope we will stick to that.

1 Like

.markdown was Gruber’s preference/intent; I suggest we go with that.

I think .md is more common these days. There’s more than 5 times as many on Github as there are README.markdown:

I don’t think there’s any reason that CommonMark(down) should mandate one or the other. Most apps that deal with Markdown files understand both of them, and probably most of the less common variants too.


I guess a related question is, what’s the proper MIME type to use for Markdown / CommonMark data?

I prefer .md as well and it does seem to be very widely used. I think we should include .md and .markdown but not the others unless there is a good reason to.

There is no official mime type, but text/x-markdown looks like a good bid, see What is the mime type for markdown? (StackOverflow).


Why x-markdown instead of just markdown? My understanding was the x- prefix was normally there for unstandardized formats? But this is standard markdown (commonmark now) right?

1 Like

The x- indicates that it’s a non-standard MIME-type, not that the file format itself is not standardized – the standard MIME-types are only those appearing on this list: – and getting on that list is not easy. If you look at the text/* section, there are very few standard mimetypes that are not vendor-specific types (like vnd.debian.copyright).

A famous example of this is JSON (which is application/json rather than text/json) – JavaScript itself is, of course, text/javascript.

So in short, until Markdown gets on the list, I’ll have to be text/x-markdown or similar.


Thank you, that makes sense. I was clearly confused.

On the other hand, RFC 6648 deprecates such “x-” prefixes.

1 Like

Yeah, it’s a tricky problem. Until we could get a proper MIME type delegation from IANA, there are basically no clear choice, because whatever we pick might get rejected by IANA.

We could try for something like text/vnd.commonmark.markdown, since, as I understand it, the bar for vendor-specific MIME-types is significantly lower than the universal ones (ie. text/markdown).

I don’t see how that is at all relevant. And for those who think it matters what he personally prefers, be warned that he is as likely as not to be “infuriated” that files called foo.markdown contain CommonMark content.

In any case, tools that need to identify files containing this stuff, whatever it’s called, should accept whatever extensions are in common use.


I just meant it’s best to keep close to Gruber’s intention with the original spec unless there is a good reason to diverge. It helps prevent fragmentation to have something to appeal to. Although technically .markdown isn’t in the spec itself.

I know what you meant … but you yourself don’t seem to understand or be aware of the assumptions – or perhaps worldview – behind your statement. Again, Gruber’s intentions are irrelevant … especially now that he has gone so far out of his way not only to distance himself from this standardization effort and to denigrate it and the people behind it (“a group I don’t agree with”), but to drive a wedge between members of the community and sow confusion forever after because of this cockamamie “CommonMark” name for a standardized spec for Markdown.

Sort of like how, technically, I’m not the queen of Romania.

Not only isn’t it in the spec itself, it isn’t in anything. All we have is Gruber saying, long after he produced anything related to Markdown, that .markdown is the only extension that he would endorse (not even that he does endorse it). Again, Gruber’s preferences are completely and utterly irrelevant … all that is relevant is what is commonly used by the community. For that reason, .md is the preferred extension, but as I said, tools that need to identify files containing this sort of markup should accept .md, .markdown, and any other extension in common use.

Markdown has a very well thought out aesthetic, and I think that’s linked to Gruber’s opinionated nature. I suspect many of us are here because we want to build upon (some of) his preferences/intentions for Markdown, even if we don’t agree with all of them. That said, I agree with either .markdown or .md for the reasons already outlined in this topic.

If I remember correctly many text editors have followed TextMate’s example and support a variety of file extensions: .md, .mdown, .markdown, and .markdn

Does it make sense for the spec to support more than one file extension? I’m personally a huge fan of .md even though I know .markdown is supposed to be the standard. How much does backwards compatibility with existing documents matter?

There’s that workdview again. I suggest that you read