CommonMark

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet" type="text/css"> <link href="https://fonts.googleapis.com/css?family=Roboto+Mono" rel="stylesheet" type="text/css"> <link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen">  <link rel="icon" type="image/png" href="/images/markdown-mark-apple-touch.png"> <link rel="apple-touch-icon" type="image/png" href="/images/markdown-mark-apple-touch.png"> <title>CommonMark</title> <meta name="viewport" content="width=device-width, initial-scale=1"> </head> <body> <div id="container"> <section class="inner"> <header> <h1>CommonMark</h1> <h2>A strongly defined, highly compatible specification of Markdown</h2> </header> <section id="main_content"> <h2> <a id="what" class="anchor" href="#what"></a>What is Markdown? </h2> <p> It’s a plain text format for writing structured documents, based on formatting conventions from email and usenet. </p> <p> <a href="//commonmark.org/help/" class="button-primary">Learn Markdown in 60 Seconds</a> </p> <h2> <a id="created" class="anchor" href="#what"></a>Who created Markdown? </h2> <p> It was <a href="https://en.wikipedia.org/wiki/Markdown#History">developed in 2004 by John Gruber in collaboration with Aaron Swartz</a>. Gruber wrote the first markdown-to-html converter in Perl, and it soon became widely used in websites. By 2014 there were dozens of implementations in many languages. </p> <h2> <a id="why" class="anchor" href="#why"></a>Why is CommonMark needed? </h2> <p> John Gruber’s <a href="https://daringfireball.net/projects/markdown/syntax">canonical description of Markdown’s syntax</a> does not specify the syntax unambiguously. </p> <p> In the absence of a spec, early implementers consulted the original <code>Markdown.pl</code> code to resolve these ambiguities. But <code>Markdown.pl</code> was quite buggy, and gave manifestly bad results in many cases, so it was not a satisfactory replacement for a spec. <code>Markdown.pl</code> was last updated December 17<small>th</small>, 2004. <p> Because there is no unambiguous spec, implementations have diverged considerably over the last 10 years. As a result, users are often surprised to find that a document that renders one way on one system (say, a GitHub wiki) renders differently on another (say, converting to docbook using Pandoc). To make matters worse, because nothing in Markdown counts as a “syntax error,” the divergence often isn’t discovered right away. </p> <p> There’s no standard test suite for Markdown; <a href="https://github.com/michelf/mdtest/">MDTest</a> is the closest thing we had, and is now obsolete. The best current way to resolve Markdown ambiguities and inconsistencies is <a href="https://babelmark.github.io/">Babelmark 3</a>, which compares the output of 20+ implementations of Markdown against each other to see if a consensus emerges. </p> <p> We propose a <strong>standard, unambiguous syntax specification for Markdown</strong>, along with a <strong>suite of comprehensive tests</strong> to validate Markdown implementations against this specification. We believe this is necessary, even essential, for the future of Markdown. </p> <p> That’s what we call <strong>CommonMark</strong>. <a href="https://github.com/dcurtis/markdown-mark"><img src="images/markdown-mark.png" height="22" width="36" alt="Markdown Logo" style="vertical-align:top" /></a> </p> <p> </p> <h2> <a id="who" class="anchor" href="#who-today"></a>Who are you today? </h2> <p>We’re a group of Markdown fans continually working toward the vision of CommonMark — a standard, interoperable and testable version of Markdown.</p> <ul> <li><strong>John MacFarlane</strong>, jgm@berkeley.edu</li> <li><strong>Martin Woodward</strong>, martinwoodward@github.com</li> <li><strong>Jeff Atwood</strong>, jatwood@codinghorror.com</li> </ul> <h2> <a id="who" class="anchor" href="#who"></a>Who were you in 2014, when this started? </h2> <p>We’re a group of Markdown fans who either work at companies with industrial scale deployments of Markdown, have written Markdown parsers, have extensive experience supporting Markdown with end users – or all of the above. </p> <ul> <li><strong>John MacFarlane</strong>, of Pandoc</li> <li><strong>David Greenspan</strong>, of Meteor</li> <li><strong>Vicent Marti</strong>, of GitHub</li> <li><strong>Neil Williams</strong>, of Reddit</li> <li><strong>Benjamin Dumke-von der Ehe</strong>, of Stack Overflow / Stack Exchange</li> <li><strong>Jeff Atwood</strong>, of Discourse</li> </ul> <h2> <a id="how" class="anchor" href="#how"></a>How can I help? </h2> <p>Exercise our <a href="https://github.com/commonmark">reference implementations</a>, or <a href="https://github.com/jgm/CommonMark/wiki/List-of-CommonMark-Implementations">find a community implementation</a> in your preferred environment or language. Provide <a href="https://talk.commonmark.org"></a>feedback!</p> <p>If a CommonMark implementation does not already exist in your preferred environment or language, try <strong>implementing your own CommonMark parser</strong>. One of our major goals is to <a href="https://spec.commonmark.org/">strongly specify Markdown</a>, and to eliminate the many old inconsistencies and ambiguities that made using Markdown so difficult. Did we succeed?</p> <h2> <a id="where" class="anchor" href="#where"></a>Where can I find it? </h2> <h3> <a href="https://spec.commonmark.org/">spec.commonmark.org</a> </h3> <p> The CommonMark specification. </p> <h3> <a href="https://github.com/commonmark">code.commonmark.org</a> </h3> <p> Reference implementation and validation test suite on GitHub. </p> <h3> <a href="https://talk.commonmark.org/">talk.commonmark.org</a> </h3> <p> Public discussion area and mailing list via <a href="https://www.discourse.org">Discourse</a>. </p> <h3> <a href="https://commonmark.org/help">commonmark.org/help</a> </h3> <p> Quick reference card and interactive tutorial for learning Markdown. </p> <h3> <a href="https://spec.commonmark.org/dingus/">spec.commonmark.org/dingus</a> </h3> <p> Live testing tool powered by the reference implementation. </p> <h2> <a id="when" class="anchor" href="#when"></a>When is the spec final? </h2> <p> The current version of the CommonMark spec is quite robust after many years of public feedback. </p> <p> There are currently CommonMark implementations for <a href="https://github.com/commonmark/commonmark-spec/wiki/List-of-CommonMark-Implementations">dozens of programming languages</a>, and the following sites and projects have adopted CommonMark: <ul> <li>Discourse</li> <li>GitHub</li> <li>GitLab</li> <li>Reddit</li> <li>Qt</li> <li>Stack Overflow / Stack Exchange</li> <li>Swift</li> </ul> </p> </section> <p><span style="color:maroon"><3</span></p> </section> </div> </body> </html>

CINXE.COM

CommonMark