Allow markup language to be set in YAML rather than file extension #230

waylan opened this Issue Nov 7, 2010 · 4 comments


None yet
5 participants

waylan commented Nov 7, 2010

This recently came up (again) in the Markdown community. There is no standard markdown file extension. In fact, Markdown's creator (John Gruber) uses .text which offers no hint of what markup language is used. Sure, I can run my own instance of Jekyll with .text set to invoke the markdown parser, but why should I need to?

Every source file has a YAML section. Why can't that define the markup language used within? That way I can use whatever file extension I want. Personally, I would like to see a default set in _config.yml which can be overridden on an individual basis in each files YAML section. Of course, when neither is set, the current behavior should continue.


mojombo commented Dec 14, 2010

Why not just use one of the fairly accepted extensions? That's what they're for. It's crazy to use .text when the content is clearly not just text. Using the extension for the format makes things simple and easy to understand.

waylan commented Dec 14, 2010

Why not just use one of the fairly accepted extensions?

I could, but the the controlling authority (on Markdown - John Gruber) refuses to endorse any of them.

And every time someone brings this us, someone else always counters that using file extensions to determine file type was a bad idea from the get-go. I wont' go that far, but consider this:

Suppose I have a file which I have tracked changes of in a git repo. That file is formatted as a markdown document. Suppose I now want to reformat that same document as a reStructuredText document to take advantage of reStructuredText's more powerful features. If I'm required to change the file name, then git sill show the old file as being deleted and the new file as being created. It's not as easy to track the history of the file anymore.

Another argument is that I might want to provide the unformatted text of my web pages to my end users with urls where the file extension is changed from ".html" to .something (i.e.: and If at some point I need/want to change the format used in the text, my url has now changed (perhaps from ".md" to ".rst"). If, however, I was using ".txt" or similar, this is not an issue.

So, I would say that using the file extension is "crazy" (to use your word) and makes things more complex. Whereas if the format is defined within the file metadata (which exists anyway), that is simple and easy.

However, I'm not asking for you to abandon the existing system which is obviously working fine for many users, but to simply add the ability to define the markup language a second way for those who may prefer it that way. I'm certainly not alone in that desire.

I use .md which is nice, short and to the point.


parkr commented Feb 20, 2013

It's been two years since this issue, and I think we've got this all figured out in the markdown community: .md, .mkdn, .markdown. Take your pick. Setting this for each file is not a sustainable option for most people. A global option might make sense, but not a per-post option.

@parkr parkr closed this Feb 20, 2013

@jekyllbot jekyllbot locked and limited conversation to collaborators Feb 27, 2017

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.