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
|
---
title: CommonMark
...
CommonMark is a [specification of Markdown
syntax](http://jgm.github.io/stmd/spec.html), together with
BSD3-licensed implementations (`stmd`) in C and javascript. The source
for the spec and the two implementations can be found in [this
repository](http://github.com/jgm/stmd).
The C implementation provides both a library and a standalone program
`stmd` that converts Markdown to HTML. It is written in standard C99 and
has no library dependencies.
The javascript implementation is a single javascript file, with no
dependencies. [Try it now!](http://jgm.github.io/stmd/js/)
[The spec](http://jgm.github.io/stmd/spec.html) contains over 400
embedded examples which serve as conformance tests. (The source contains
a perl script that will run the tests against any Markdown program.)
The spec is written from the point of view of the human writer, not the
computer reader. It is not an algorithm—an English translation of a
computer program—but a declarative description of what counts as a block
quote, a code block, and each of the other structural elements that can
make up a Markdown document. For the most part, the spec limits itself
to the basic elements described in John Gruber’s [canonical syntax
description](http://daringfireball.net/projects/markdown/syntax),
eschewing extensions like footnotes and definition lists. It is
important to get the core right before considering such things.
Because Gruber’s syntax description leaves many aspects of the syntax
undetermined, writing a precise spec requires making a large number of
decisions, many of them somewhat arbitrary. In making them, I have
appealed to existing conventions and considerations of simplicity,
readability, expressive power, and consistency. I have tried to ensure
that “normal” documents in the many incompatible existing
implementations of Markdown will render, as far as possible, as their
authors intended. And I have tried to make the rules for different
elements work together harmoniously. In places where different decisions
could have been made (for example, the rules governing list
indentation), I have explained the rationale for my choices. In a few
cases, I have departed slightly from the canonical syntax description,
in ways that I think further the goals of Markdown as stated in that
description.
There are only a few places where this spec says things that contradict
the canonical syntax description:
- It [allows all punctuation symbols to be
backslash-escaped](http://jgm.github.io/stmd/spec.html#backslash-escapes),
not just the symbols with special meanings in Markdown. I found
that it was just too hard to remember which symbols could be
escaped.
- It introduces an [alternative syntax for hard line
breaks](http://jgm.github.io/stmd/spec.html#hard-line-breaks), a
backslash at the end of the line, supplementing the
two-spaces-at-the-end-of-line rule. This is motivated by persistent
complaints about the “invisible” nature of the two-space rule.
- Link syntax has been made a bit more predictable (in a
backwards-compatible way). For example, `Markdown.pl` allows single
quotes around a title in inline links, but not in reference links.
This kind of difference is really hard for users to remember, so the
spec [allows single quotes in both
contexts](http://jgm.github.io/stmd/spec.html#links).
- The rule for HTML blocks differs, though in most real cases it
shouldn't make a difference. (See
[here](http://jgm.github.io/stmd/spec.html#html-blocks) for
details.) The spec's proposal makes it easy to include Markdown
inside HTML block-level tags, if you want to, but also allows you to
exclude this. It is also makes parsing much easier, avoiding
expensive backtracking.
- It does not collapse adjacent bird-track blocks into a single
blockquote:
> this is two
> blockquotes
> this is a single
>
> blockquote with two paragraphs
- Rules for content in lists differ in a few respects, though (as with
HTML blocks), most lists in existing documents should render as
intended. There is some discussion of the choice points and
differences [here](http://jgm.github.io/stmd/spec.html#motivation).
I think that the spec's proposal does better than any existing
implementation in rendering lists the way a human writer or reader
would intuitively understand them. (I could give numerous examples
of perfectly natural looking lists that nearly every existing
implementation flubs up.)
- The spec stipulates that two blank lines break out of all list
contexts. This is an attempt to deal with issues that often come up
when someone wants to have two adjacent lists, or a list followed by
an indented code block.
- Changing bullet characters, or changing from bullets to numbers or
vice versa, starts a new list. I think that is almost always going
to be the writer's intent.
- The number that begins an ordered list item may be followed by
either `.` or `)`. Changing the delimiter style starts a new
list.
- The start number of an ordered list is significant.
- [Fenced code blocks](http://jgm.github.io/stmd/spec.html#fenced-code-blocks) are supported, delimited by either
backticks (` ``` `) or tildes (` ~~~ `).
In all of this, I have been guided by eight years experience writing
Markdown implementations in several languages, including the first
Markdown parser not based on regular expression substitutions
([pandoc](http://github.com/jgm/pandoc)) and the first Markdown parsers
based on PEG grammars
([peg-markdown](http://github.com/jgm/peg-markdown),
[lunamark](http://github.com/jgm/lunamark)). Maintaining these projects
and responding to years of user feedback have given me a good sense of
the complexities involved in parsing Markdown, and of the various design
decisions that can be made. I have also explored differences between
Markdown implementations extensively using [babelmark
2](http://johnmacfarlane.net/babelmark2/). In the early phases of
working out the spec, I benefited greatly from collaboration with David
Greenspan, and from extensive discussions with a group of industrial
users of Markdown, including Jeff Atwood, Vincent Marti, and Neil
Williams.
### Contributing
There is a [forum for discussing
CommonMark](http://talk.commonmark.org); you should use it instead of
github issues for questions and possibly open-ended discussions.
Use the [github issue tracker](http://github.com/jgm/stmd/issues)
only for simple, clear, actionable issues.
|
