File extension for CommonMark?

That simply is not correct. There is no basis for it whatsover. All we have is John Gruber being asked what extension should be used and his response was that .markdown is the only one that he would endorse … he didn’t even say he does endorse it. And a personal endorsement by an individual, especially one who has been uninvolved with it for a decade, is in no way “the standard”.

Er, um, what do you think the point of standardizing existing practice is?

I think it’s okay for an ego to drive/influence a project (especially the parts which are subjective), so long you have the freedom to change the parts that matter to you.

It might be better to say that I’m appealing to a particular philosophy advocated by Gruber: readability above all else. The .markdown extension is consistent with this.

That is sensible. Indeed it is far better to appeal to philosophies than to particular personalities (especially when that personality has demonstrated so many flaws of late).

John failed to follow Guido when he had the chance, so the authority of his preferred extension should not be a primary consideration.

More to the point, however, is why do we need a default extension at all?

With respect to mime, are we trying to get browsers to render CM directly?

Otherwise, stmd and its progeny certainly don’t depend on the extension. I’m no longer sure about windows, but at least in OSX if you want to use a file extension associated with a specific program, you’re free do.

1 Like

The Internet media type text/markdown is in the process of being registered.

I am the author of draft-ietf-appsawg-text-markdown: The text/markdown Media Type, which has been adopted as an IETF Applications Area Working Group item. It’s making its way through. Comments on the draft should be directed to the apps-discuss mailing list.

Regarding the file extension: my draft registers both .md and .markdown. Media type registrations are not authoritative on the topic of file extensions; however, nothing is. Personally I prefer .markdown. I know, however, there are enough (and other) files out there in existence, that we should not pretend about .md these days.


Ok, thanks for the information (and for your efforts in that regard).

1 Like

That’s probably mostly because Github doesn’t (didn’t?) automatically display README.markdown, but did display Very poor metric.

If you have better information, I’m all ears.

In my experience (using lots of different Markdown-related tools), .md is the most common extension, with .markdown a distant second. The rest of them (.mdown, .mkdn or whatever) I’ve never encountered in the wild (but some of the editors I’ve used support them).


Why you want to reuse the Markdown extension? CommonMark is not Markdown.

After reading previous comments, I propose .mark and text/mark for the MIME-type.

They are both unused.

1 Like

.mark sounds good, though .md is used more often. If commonmark is highly compatible with gruber’s markdown, just stick to .md, if not then try .mark.

Btw, just notice that R statistic program name their fancy styled markdown document as .rmd to indicate that it is a markdown formatted document that has inline executable R snippets.

Whatever extension you choose like .md or .mark, I recommend adding a ‘Recommendation’ for filenames like .R.mark for R or .py.mark for python. So at least the file can be read even if there is no python or R hooks in the CommomMark reader.

1 Like

For any file claiming to contain Markdown, the .markdown extension is the most readable and logical. The .md extension is most widely used. All other variations (.mdown, .mkdn, .markdn) are neither readable nor widely used, and as there are 49 ways of arranging the letters of the word into an extension, we should ignore those all.

However, to call CommonMark Markdown would be similar to calling LESS and SASS CSS. Yes, the original subset is still supported in the new language, but the new language is so much more.

Unless CommonMark’s development halts today, it will be a very different beast next year. It will support syntaxes and extensions that have never been valid Markdown. Just like how CommonMark has a name that’s distinct from Markdown, I support giving it an extension and MIME-type distinct from Markdown, and I like Sanpi’s proposed .mark extension.


Why you want to reuse the Markdown extension? CommonMark is not Markdown.

CommonMark is Markdown (I mean, every cmark implementation works as a markdown parser, but the opposite isn’t true).

Thus, .md extension works just fine here. It is popular, and cmark just doesn’t differ enough to warrant a change.

Not exactly: Is CommonMark really Markdown "compatible"?

A new extension doesn’t means you can’t parse .md file as CommonMark, but prevent parsing CommonMark file with a markdown parser.

1 Like

@Tewha7 GitHub displays both .md and .markdown (for at least 8 months), see

I don’t think there’s any need to support anything but .md and .markdown. Short version, long version — anything in between doesn’t make much sense.

1 Like

I realize .md is the most common extension, however it’s also used by GCC machine description files and Modula. Vim, for example, only recognizes .md as Markdown in by default [source]. The second most widely supported extension is .markdown. Other extensions are not supported everywhere (for example, the second shortest .mkd is not supported by Bitbucket) and I find them unreadable anyway.

Conclusion: In my opinion, .markdown should be the officially endorsed standard, but tools should probably also support at least .md where feasible.


Syntax highlighters need either an extension or a hashbang, else they have to resort to more complicated heuristics.

A common convention on Unix/Linux systems is for executable files to have a hashbang and no extension, and for libraries to have an extension (.pl, .py, .rb, etc.) and no hashbang.

You can’t really have extensionless files on Windows; for example, README will be recognized as a README file.

Therefore, Markdown certainly does need an extension. Now, I’m not saying there should be just “one true extension”, but a standard would be certainly nice—one that makes sense, i.e. not something like .text.

This is a good reason to recommend .markdown as the primary/official file extension instead of .md.

But first there should probably be some kind of standard extension.

We were having discussion elsewhere where one person wanted to change file ending from .md to .markdown, but it was stopped with two reasons:

  1. there is no standardized filetype extension
  2. “.md is better because it is shorter I don’t want file names to take my whole screen in width”

Is it possible to also use the ‘naturalization argument’? That the majority of markdown files out there in the wild is already named “.md”, so any files we read should be in “.md” (if we are strictly compatible with majority of markdown formatted files).

If we are not strictly compatible with majority of markdown files, then we should use .cm or .mark, or .mk. Thought an argument can be made that .md is a generic file extension for lightly marked up text, and thus is not markdown specific.

That might be the way to go and we could also to look at the extension apps save Markdown files in. I personally use iA Writer for Mac which saves files with the .md extension by default (but recognises other extensions like .markdown). We could do a comparison of apps which read and write Markdown files and list what file extensions are used.