This is a wiki page to work on Goals and Use Cases for Markdown (as a formatting syntax) and text/markdown (as a media type).


The purpose of this brainstorming area is to list why people use Markdown, and why people need text/markdown. Anyone in the Internet community can edit this page. If you do not wish to log in, please submit your suggestions, goals, and use cases to the draft author (Sean Leonard).

Use Cases for Markdown

This section lists use cases for Markdown content on modern computing systems. This section is about Markdown as a formatting syntax; it has nothing to do with the text/markdown media type. Where do you use Markdown? Why did you choose to use Markdown instead of something else?

  • in any HTML composing workflow, being able to type out "easy code" and have a processor spit out valid HTML
  • comments in a web forum
  • GitHub commit messages
  • writing files. They have some formatting, but can be read with a plain text editor
  • writing "safe" HTML (no hidden script tags, no XSS attack vectors, etc.)
  • writing plain text e-mail messages with things like links in [1] style instead of inline
  • writing documents that focus on content, rather than framing (e.g., writing documents in a CMS so you don't have to deal with navigation bars, advertisements, third-party Javascript, frames, or any of that other junk)
  • writing HTML fragments and not needing to deal with all that <head> stuff
  • getting people to write formatted text
  • what-you-see-is-what-you-get: easy to make a split screen view with text (with Markdown codes) on the left, and formatted HTML on the right, without needing to add a lot of GUI buttons and keyboard shortcuts (i.e., death to Ctrl+B)
  • expressing basic ideas like *emphasis* without relying on <em>tagging</em> complexities
  • writing documents without _consequences_: consequences usually being the penalty of seeing "invalid" being spit out of a processor, and thus having to go back and debug it. Markdown documents aren't invalid--they have the same utility level as a notepad on your desk.

(Please continue to add to this section.)

Use Cases for the text/markdown Media Type

Some people have raised questions as to why a text/markdown media type is necessary. Put some reasons why you need a standard media type here.

Back in 2007, one user reported that his CMS, Railfrog, uses media types to select appropriate processing. A Markdown type is therefore necessary--using a file extension is not sufficient.

Markdown content is just a sequence of text (i.e., a character stream). One can't assume that Markdown is stored in files ending in .md or .markdown. There needs to be more metadata stored alongside the character stream, indicating what it is.

People are already using text/x-markdown. That is considered "bad". (It also demonstrates that people do really want to label their content with an Internet media type.)

Getting a media type through IETF Consensus is hard. Implementers will not do the work required to document every last nuance of the individual variation of Markdown via dozens of media type registrations. Then there is the matter of propagating those media type registrations to all the different media type software out there, including operating systems, web servers, content management systems, etc. Furthermore, since all of the implementations interoperate more or less (more, for the most part), it makes sense for them to share a common media type.

Since it is desirable to unify all Markdown variations under one media type (text/markdown), and since there is no way to include "metadata" in a way that is common to all Markdown implementations (i.e., those being or derived from Gruber's original Markdown syntax and implementation), an appropriate way to include the variation specifier is in one or more media type parameters. For example, "Content-Type: text/markdown; variant=pandoc" illustrates how such a parameter could work.

Last modified 8 years ago Last modified on 06/11/14 21:09:06