File extension for CommonMark?

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.

It’s a poor metric because without the file being present, Github tells you to create a file called Not a file called or README.markdown.

If you don’t see that as a black mark big enough to make the metric useless, I’m honestly not sure how why we’d continue this conversation.

It doesn’t really matter why ~90% of Markdown files use .md. It only matters that they do.

The purpose of Common Markdown is not not invent new stuff. It’s to standardize what’s already there.

1 Like

In standardizing a thing explicitly not to be standardized, a new thing is created. That appears to be recognized, as a new name was picked. A new extension should be picked as well.

It does not prevent Markdown from being processed by Commonmark. It prevents Commonmark from being processed by Markdown.

The half in/half our nature of this project will be its undoing. I’ve already lost most of my interest in the project as a whole over this thread.