The initial description of Markdown[10] contained ambiguities and raised unanswered questions, causing implementations to both intentionally and accidentally diverge from the original version. This was addressed in 2014 when long-standing Markdown contributors released CommonMark, an unambiguous specification and test suite for Markdown.[11]
In 2002 Aaron Swartz created atx and referred to it as "the true structured text format". Gruber created the Markdown language in 2004, with Swartz acting as beta tester,[3][4] had the goal of enabling people "to write using an easy-to-read and easy-to-write plain text format, optionally convert it to structurally valid XHTML (or HTML)."[5]
Its key design goal was readability, that the language be readable as-is, without looking like it has been marked up with tags or formatting instructions,[9] unlike text formatted with 'heavier' markup languages, such as Rich Text Format (RTF), HTML, or even wikitext (each of which have obvious in-line tags and formatting instructions which can make the text more difficult for humans to read).
Gruber wrote a Perl script, Markdown.pl, which converts marked-up text input to valid, well-formed XHTML or HTML and replaces angle brackets (<, >) and ampersands (&) with their corresponding character entity references. It can take the role of a standalone script, a plugin for Blosxom or a Movable Type, or of a text filter for BBEdit.[5]
Rise and divergence
As Markdown's popularity grew rapidly, many Markdown implementations appeared, driven mostly by the need for additional features such as tables, footnotes, definition lists,[note 1] and Markdown inside HTML blocks.
The behavior of some of these diverged from the reference implementation, as Markdown was only characterised by an informal specification[14] and a Perl implementation for conversion to HTML.
At the same time, a number of ambiguities in the informal specification had attracted attention.[15] These issues spurred the creation of tools such as Babelmark[16][17] to compare the output of various implementations,[18] and an effort by some developers of Markdown parsers for standardisation. However, Gruber has argued that complete standardization would be a mistake: "Different sites (and people) have different needs. No one syntax would make all happy."[19]
Gruber avoided using curly braces in Markdown to unofficially reserve them for implementation-specific extensions.[20]
From 2012, a group of people, including Jeff Atwood and John MacFarlane, launched what Atwood characterised as a standardisation effort.[11] A community website now aims to "document various tools and resources available to document authors and developers, as well as implementors of the various Markdown implementations".[23] In September 2014, Gruber objected to the usage of "Markdown" in the name of this effort and it was rebranded as CommonMark.[24][25] CommonMark.org published several versions of a specification, reference implementation, test suite, and "[plans] to announce a finalized 1.0 spec and test suite in 2019."[26] No 1.0 spec has since been released as major issues still remain unsolved.[27] Nonetheless, the following websites and projects have adopted CommonMark: Discourse, GitHub, GitLab, Reddit, Qt, Stack Exchange (Stack Overflow), and Swift.
In March 2016 two relevant informational Internet RFCs were published:
Depending on implementation, basic inline HTML tags may be supported.[33] Italic text may be implemented by _underscores_ and/or *single-asterisks*.[34]
GitHub Flavored Markdown
GitHub had been using its own variant of Markdown since as early as 2009,[35] which added support for additional formatting such as tables and nesting block content inside list elements, as well as GitHub-specific features such as auto-linking references to commits, issues, usernames, etc. In 2017, GitHub released a formal specification of its GitHub Flavored Markdown (GFM) that is based on CommonMark.[29] It is a strict superset of CommonMark, following its specification exactly except for tables, strikethrough, autolinks and task lists, which GFM adds as extensions.[36] GitHub also changed the parser used on their sites accordingly, which required that some documents be changed. For instance, GFM now requires that the hash symbol that creates a heading be separated from the heading text by a space character.
Markdown Extra
Markdown Extra is a lightweight markup language based on Markdown implemented in PHP (originally), Python and Ruby.[37] It adds the following features that are not available with regular Markdown:
LiaScript[41] is a Markdown dialect that was designed to create interactive educational content. It is implemented in Elm and TypeScript and adds additional syntax elements to define features like:
JavaScript is natively supported and can be attached to various elements, this way code fragments can be made executable and editable
Examples
Text using Markdown syntax
Corresponding HTML produced by a Markdown processor
Text viewed in a browser
Heading=======Sub-heading-----------# Alternative heading## Alternative sub-heading
Paragraphs are separated
by a blank line.
Two spaces at the end of a line
produce a line break.
<h1>Heading</h1><h2>Sub-heading</h2><h1>Alternative heading</h1><h2>Alternative sub-heading</h2><p>Paragraphs are separated
by a blank line.</p><p>Two spaces at the end of a line<br/>
produce a line break.</p>
Heading
Sub-heading
Alternative heading
Alternative sub-heading
Paragraphs are separated
by a blank line.
Two spaces at the end of a line
produce a line break.
Text attributes _italic_, **bold**, `monospace`.
Horizontal rule:
---
<p>Bullet lists nested within numbered list:</p><ol><li>fruits <ul><li>apple</li><li>banana</li></ul></li><li>vegetables <ul><li>carrot</li><li>broccoli</li></ul></li></ol>
Bullet lists nested within numbered list:
fruits
apple
banana
vegetables
carrot
broccoli
A [link](http://example.com).
> Markdown uses email-style
characters for blockquoting.
>> Multiple paragraphs need to be prepended individually.
Most inline <abbr title="Hypertext Markup Language">HTML</abbr> tags are supported.
<p>A <ahref="http://example.com">link</a>.</p><p><imgalt="Image"title="icon"src="Icon-pictures.png"/></p><blockquote><p>Markdown uses email-style characters for blockquoting.</p><p>Multiple paragraphs need to be prepended individually.</p></blockquote><p>Most inline <abbrtitle="Hypertext Markup Language">HTML</abbr> tags are supported.</p>
Markdown uses email-style characters for blockquoting.
Multiple paragraphs need to be prepended individually.
Most inline HTML tags are supported.
Implementations
Implementations of Markdown are available for over a dozen programming languages; in addition, many applications, platforms and frameworks support Markdown.[42] For example, Markdown plugins exist for every major blogging platform.[43]
While Markdown is a minimal markup language and is read and edited with a normal text editor, there are specially designed editors that preview the files with styles, which are available for all major platforms. Many general-purpose text and code editors have syntax highlighting plugins for Markdown built into them or available as optional download. Editors may feature a side-by-side preview window or render the code directly in a WYSIWYG fashion.
Some apps, services and editors that support Markdown as an editing format, including:
Obsidian is note-taking software based on Markdown files.[54]
The GNOME Evolution email client supports composing messages in Markdown format,[55] with the ability to send and render emails in pure Markdown format (Content-Type: text/markdown;) or to convert Markdown to plaintext or HTML email when sending.
^Gruber, John (8 January 2014). "The Markdown File Extension". The Daring Fireball Company, LLC. Archived from the original on 12 July 2020. Retrieved 27 March 2022. 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.
^ abcLeonard, Sean (March 2016). "The text/markdown Media Type". Request for Comments: 7763. Internet Engineering Task Force. Archived from the original on 22 March 2022. Retrieved 27 March 2022. This document registers the text/markdown media type for use with Markdown, a family of plain-text formatting syntaxes that optionally can be converted to formal markup languages such as HTML.
^ abSwartz, Aaron (2004-03-19). "Markdown". Aaron Swartz: The Weblog. Archived from the original on 2017-12-24. Retrieved 2013-09-01.
^ abLeonard, Sean (March 2016). "Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations". Request for Comments: 7764. Internet Engineering Task Force. Archived from the original on 17 April 2022. Retrieved 27 March 2022. This document elaborates upon the text/markdown media type for use with Markdown, a family of plain-text formatting syntaxes that optionally can be converted to formal markup languages such as HTML. Background information, local storage strategies, and additional syntax registrations are supplied.
^ abcdMarkdown Syntax "Daring Fireball – Markdown – Syntax". 2013-06-13. "Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. While Markdown's syntax has been influenced by several existing text-to-HTML filters — including Setext, atx, Textile, reStructuredText, Grutatext[12], and EtText[13] — the single biggest source of inspiration for Markdown's syntax is the format of plain text email."
^Gruber, John (19 May 2022). "Markdoc". Daring Fireball. Archived from the original on 19 May 2022. Retrieved May 19, 2022. I love their syntax extensions — very true to the spirit of Markdown. They use curly braces for their extensions; I'm not sure I ever made this clear, publicly, but I avoided using curly braces in Markdown itself — even though they are very tempting characters — to unofficially reserve them for implementation-specific extensions. Markdoc's extensive use of curly braces for its syntax is exactly the sort of thing I was thinking about.
^"CommonMark". Archived from the original on 12 April 2016. Retrieved 20 Jun 2018. The current version of the CommonMark spec is complete, and quite robust after a year of public feedback … but not quite final. With your help, we plan to announce a finalized 1.0 spec and test suite in 2019.
^"Basic Syntax: Italic". The Markdown Guide. Matt Cone. Archived from the original on 26 March 2022. Retrieved 27 March 2022. To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces around the letters.
