forked from commonmark/commonmark-web
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
165 lines (145 loc) · 9.08 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
<!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">
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<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 have. The only way to resolve Markdown ambiguities and inconsistencies is <a href="https://johnmacfarlane.net/babelmark2/">Babelmark</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://code.commonmark.org/">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://code.commonmark.org/">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>