-
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathbreakdance-example-commonmark.html
executable file
·12745 lines (12488 loc) · 485 KB
/
breakdance-example-commonmark.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
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>CommonMark Spec</title>
<style type="text/css">
body { font-family: Helvetica, arial, freesans, clean, sans-serif;
line-height: 1.4;
max-width: 48em;
margin: auto;
color: #333333;
background-color: #fff;
font-size: 13pt;
}
div#TOC ul { list-style: none; }
h1 { font-size: 140%; font-weight: bold; border-top: 1px solid gray; padding-top: 0.5em; }
h2 { font-size: 120%; font-weight: bold; }
h3 { font-size: 110%; font-weight: bold; }
h4 { font-size: 100%; font-weight: bold; }
a.definition { font-weight: bold; }
span.space { position: relative; }
span.number:after { content: " " }
span.space:after {
content: "·";
position: absolute;
/* create a mark that indicates a space (trick from D. Greenspan) */
top: 0px; bottom: 7px; left: 1px; right: 1px;
color: #AAA;
}
div.example { overflow: hidden; }
p { text-align: justify; }
pre { padding: 0.5em; margin-left: 0; margin-right: 0; margin-top: 0.2em;
margin-bottom: 0.5em; font-size: 88%; }
pre {
white-space: pre-wrap; /* css-3 */
white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
white-space: -pre-wrap; /* Opera 4-6 */
white-space: -o-pre-wrap; /* Opera 7 */
word-wrap: break-word; /* Internet Explorer 5.5+ */
}
code { font-family: monospace; background-color: #D3E1E4; }
pre > code { background-color: transparent; }
.example { font-size: 0; /* hack to get width:50% to work on inline-block */
padding-bottom: 6pt; }
.column pre { font-size: 11pt; padding-left: 6pt; padding-right: 6pt;
padding-top: 2pt; padding-bottom: 2pt; }
div.examplenum { font-size: 11pt; text-align: left; margin-bottom:10px; }
div.column { display: inline-block; width: 50%; vertical-align: top; }
div.example > div:nth-child(2) { clear:left; background-color: #D3E1E4; }
div.example > div:nth-child(3) { clear:right; background-color: #C9CaCE; }
#watermark {
position:fixed;
bottom:0px;
left:0px;
padding: 1em;
width: 100%;
font-size: 120%;
opacity:0.7;
z-index:99;
color: white;
}
#watermark a { color: white; }
a.dingus {
margin-left: 1em;
cursor: pointer;
line-height: 30px;
padding: 4px 7px;
color: #FFF;
background-color: #33C3F0;
box-shadow: 2px 2px 2px rgba(0,0,0,.2);
border-color: #4FCAEF;
border-bottom: 2px #2A9EC1 solid;
border-right: 2px #2A9EC1 solid;
}
a.footnoteRef > sup:before {
content: "[";
}
a.footnoteRef > sup:after {
content: "]";
}
a.footnoteRef > sup {
vertical-align: baseline;
font-size: 100%;
}
@media print {
@page {
size: auto;
margin: 1.2in 1.2in 1.2in 1.2in;
}
body {
margin: 0px;
line-height: 1.2;
font-size: 10pt;
}
.column pre { font-size: 9pt; }
div.examplenum { font-size: 9pt; }
a.dingus { display: none; }
}
</style>
<script src="https://code.jquery.com/jquery-2.2.0.min.js"></script>
<script type="text/javascript">
$(document).ready(function() {
$("div.example").each(function(e) {
var t = $(this).find('code.language-markdown').text();
$(this).find('a.dingus').click(function(f) {
window.open('/dingus/?text=' +
encodeURIComponent(t.replace(/→/g,"\t")));
});
});
$("code.language-markdown").dblclick(function(e) { window.open('/dingus/?text=' +
encodeURIComponent($(this).find('code').text()));
});
});
</script>
</head>
<body>
<h1 class="title">CommonMark Spec</h1>
<div class="version">Version 0.27 (2016-11-18)</div>
<div class="authors">
<span class="author">John MacFarlane</span>
</div>
<div class="license">
<a rel="license"
href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative
Commons BY-SA" style="border-width:0"
src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png"
/></a><br/><span style="display:none"><span xmlns:dct="http://purl.org/dc/terms/"
href="http://purl.org/dc/dcmitype/Text" property="dct:title"
rel="dct:type">CommonMark Spec</span> by
<a xmlns:cc="http://creativecommons.org/ns#"
href="http://spec.commonmark.org" property="cc:attributionName"
rel="cc:attributionURL">John MacFarlane</a> is licensed under a
<a rel="license"
href="http://creativecommons.org/licenses/by-sa/4.0/">Creative
Commons Attribution-ShareAlike 4.0 International License</a>.</span>
</div>
<div id="watermark"></div>
<div id="TOC">
<ul>
<li><a href="#introduction"><span class="number">1</span>Introduction</a>
<ul>
<li><a href="#what-is-markdown-"><span class="number">1.1</span>What is Markdown?</a></li>
<li><a href="#why-is-a-spec-needed-"><span class="number">1.2</span>Why is a spec needed?</a></li>
<li><a href="#about-this-document"><span class="number">1.3</span>About this document</a></li>
</ul>
</li>
<li><a href="#preliminaries"><span class="number">2</span>Preliminaries</a>
<ul>
<li><a href="#characters-and-lines"><span class="number">2.1</span>Characters and lines</a></li>
<li><a href="#tabs"><span class="number">2.2</span>Tabs</a></li>
<li><a href="#insecure-characters"><span class="number">2.3</span>Insecure characters</a></li>
</ul>
</li>
<li><a href="#blocks-and-inlines"><span class="number">3</span>Blocks and inlines</a>
<ul>
<li><a href="#precedence"><span class="number">3.1</span>Precedence</a></li>
<li><a href="#container-blocks-and-leaf-blocks"><span class="number">3.2</span>Container blocks and leaf blocks</a></li>
</ul>
</li>
<li><a href="#leaf-blocks"><span class="number">4</span>Leaf blocks</a>
<ul>
<li><a href="#thematic-breaks"><span class="number">4.1</span>Thematic breaks</a></li>
<li><a href="#atx-headings"><span class="number">4.2</span>ATX headings</a></li>
<li><a href="#setext-headings"><span class="number">4.3</span>Setext headings</a></li>
<li><a href="#indented-code-blocks"><span class="number">4.4</span>Indented code blocks</a></li>
<li><a href="#fenced-code-blocks"><span class="number">4.5</span>Fenced code blocks</a></li>
<li><a href="#html-blocks"><span class="number">4.6</span>HTML blocks</a></li>
<li><a href="#link-reference-definitions"><span class="number">4.7</span>Link reference definitions</a></li>
<li><a href="#paragraphs"><span class="number">4.8</span>Paragraphs</a></li>
<li><a href="#blank-lines"><span class="number">4.9</span>Blank lines</a></li>
</ul>
</li>
<li><a href="#container-blocks"><span class="number">5</span>Container blocks</a>
<ul>
<li><a href="#block-quotes"><span class="number">5.1</span>Block quotes</a></li>
<li><a href="#list-items"><span class="number">5.2</span>List items</a></li>
<li><a href="#lists"><span class="number">5.3</span>Lists</a></li>
</ul>
</li>
<li><a href="#inlines"><span class="number">6</span>Inlines</a>
<ul>
<li><a href="#backslash-escapes"><span class="number">6.1</span>Backslash escapes</a></li>
<li><a href="#entity-and-numeric-character-references"><span class="number">6.2</span>Entity and numeric character references</a></li>
<li><a href="#code-spans"><span class="number">6.3</span>Code spans</a></li>
<li><a href="#emphasis-and-strong-emphasis"><span class="number">6.4</span>Emphasis and strong emphasis</a></li>
<li><a href="#links"><span class="number">6.5</span>Links</a></li>
<li><a href="#images"><span class="number">6.6</span>Images</a></li>
<li><a href="#autolinks"><span class="number">6.7</span>Autolinks</a></li>
<li><a href="#raw-html"><span class="number">6.8</span>Raw HTML</a></li>
<li><a href="#hard-line-breaks"><span class="number">6.9</span>Hard line breaks</a></li>
<li><a href="#soft-line-breaks"><span class="number">6.10</span>Soft line breaks</a></li>
<li><a href="#textual-content"><span class="number">6.11</span>Textual content</a></li>
</ul>
</li>
<li><a href="#appendix-a-parsing-strategy">Appendix: A parsing strategy</a>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#phase-1-block-structure">Phase 1: block structure</a></li>
<li><a href="#phase-2-inline-structure">Phase 2: inline structure</a></li>
</ul>
</li>
</ul>
</div>
<h1 id="introduction" href="#introduction" class="definition">
<span class="number">1</span>Introduction
</h1>
<h2 id="what-is-markdown-" href="#what-is-markdown-" class="definition">
<span class="number">1.1</span>What is Markdown?
</h2>
<p>Markdown is a plain text format for writing structured documents,
based on conventions used for indicating formatting in email and
usenet posts. It was developed in 2004 by John Gruber, who wrote
the first Markdown-to-HTML converter in Perl, and it soon became
ubiquitous. In the next decade, dozens of implementations were
developed in many languages. Some extended the original
Markdown syntax with conventions for footnotes, tables, and
other document elements. Some allowed Markdown documents to be
rendered in formats other than HTML. Websites like Reddit,
StackOverflow, and GitHub had millions of people using Markdown.
And Markdown started to be used beyond the web, to author books,
articles, slide shows, letters, and lecture notes.</p>
<p>What distinguishes Markdown from many other lightweight markup
syntaxes, which are often easier to write, is its readability.
As Gruber writes:</p>
<blockquote>
<p>The overriding design goal for Markdown’s formatting syntax is
to make it as readable as possible. The idea is that 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.
(<a href="http://daringfireball.net/projects/markdown/">http://daringfireball.net/projects/markdown/</a>)</p>
</blockquote>
<p>The point can be illustrated by comparing a sample of
<a href="http://www.methods.co.nz/asciidoc/">AsciiDoc</a> with
an equivalent sample of Markdown. Here is a sample of
AsciiDoc from the AsciiDoc manual:</p>
<pre><code>1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.
2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.
a. This list is nested and does not require explicit item
continuation.
+
This paragraph is part of the preceding list item.
b. List item b.
This paragraph belongs to item two of the outer list.
--
</code></pre>
<p>And here is the equivalent in Markdown:</p>
<pre><code>1. List item one.
List item one continued with a second paragraph followed by an
Indented block.
$ ls *.sh
$ mv *.sh ~/tmp
List item continued with a third paragraph.
2. List item two continued with an open block.
This paragraph is part of the preceding list item.
1. This list is nested and does not require explicit item continuation.
This paragraph is part of the preceding list item.
2. List item b.
This paragraph belongs to item two of the outer list.
</code></pre>
<p>The AsciiDoc version is, arguably, easier to write. You don’t need
to worry about indentation. But the Markdown version is much easier
to read. The nesting of list items is apparent to the eye in the
source, not just in the processed document.</p>
<h2 id="why-is-a-spec-needed-" href="#why-is-a-spec-needed-" class="definition">
<span class="number">1.2</span>Why is a spec needed?
</h2>
<p>John Gruber’s <a href="http://daringfireball.net/projects/markdown/syntax">canonical description of Markdown’s
syntax</a>
does not specify the syntax unambiguously. Here are some examples of
questions it does not answer:</p>
<ol>
<li>
<p>How much indentation is needed for a sublist? The spec says that
continuation paragraphs need to be indented four spaces, but is
not fully explicit about sublists. It is natural to think that
they, too, must be indented four spaces, but <code>Markdown.pl</code> does
not require that. This is hardly a “corner case,” and divergences
between implementations on this issue often lead to surprises for
users in real documents. (See <a href="http://article.gmane.org/gmane.text.markdown.general/1997">this comment by John
Gruber</a>.)</p>
</li>
<li>
<p>Is a blank line needed before a block quote or heading?
Most implementations do not require the blank line. However,
this can lead to unexpected results in hard-wrapped text, and
also to ambiguities in parsing (note that some implementations
put the heading inside the blockquote, while others do not).
(John Gruber has also spoken <a href="http://article.gmane.org/gmane.text.markdown.general/2146">in favor of requiring the blank
lines</a>.)</p>
</li>
<li>
<p>Is a blank line needed before an indented code block?
(<code>Markdown.pl</code> requires it, but this is not mentioned in the
documentation, and some implementations do not require it.)</p>
<pre><code class="language-markdown">paragraph
code?
</code></pre>
</li>
<li>
<p>What is the exact rule for determining when list items get
wrapped in <code><p></code> tags? Can a list be partially “loose” and partially
“tight”? What should we do with a list like this?</p>
<pre><code class="language-markdown">1. one
2. two
3. three
</code></pre>
<p>Or this?</p>
<pre><code class="language-markdown">1. one
- a
- b
2. two
</code></pre>
<p>(There are some relevant comments by John Gruber
<a href="http://article.gmane.org/gmane.text.markdown.general/2554">here</a>.)</p>
</li>
<li>
<p>Can list markers be indented? Can ordered list markers be right-aligned?</p>
<pre><code class="language-markdown"> 8. item 1
9. item 2
10. item 2a
</code></pre>
</li>
<li>
<p>Is this one list with a thematic break in its second item,
or two lists separated by a thematic break?</p>
<pre><code class="language-markdown">* a
* * * * *
* b
</code></pre>
</li>
<li>
<p>When list markers change from numbers to bullets, do we have
two lists or one? (The Markdown syntax description suggests two,
but the perl scripts and many other implementations produce one.)</p>
<pre><code class="language-markdown">1. fee
2. fie
- foe
- fum
</code></pre>
</li>
<li>
<p>What are the precedence rules for the markers of inline structure?
For example, is the following a valid link, or does the code span
take precedence ?</p>
<pre><code class="language-markdown">[a backtick (`)](/url) and [another backtick (`)](/url).
</code></pre>
</li>
<li>
<p>What are the precedence rules for markers of emphasis and strong
emphasis? For example, how should the following be parsed?</p>
<pre><code class="language-markdown">*foo *bar* baz*
</code></pre>
</li>
<li>
<p>What are the precedence rules between block-level and inline-level
structure? For example, how should the following be parsed?</p>
<pre><code class="language-markdown">- `a long code span can contain a hyphen like this
- and it can screw things up`
</code></pre>
</li>
<li>
<p>Can list items include section headings? (<code>Markdown.pl</code> does not
allow this, but does allow blockquotes to include headings.)</p>
<pre><code class="language-markdown">- # Heading
</code></pre>
</li>
<li>
<p>Can list items be empty?</p>
<pre><code class="language-markdown">* a
*
* b
</code></pre>
</li>
<li>
<p>Can link references be defined inside block quotes or list items?</p>
<pre><code class="language-markdown">> Blockquote [foo].
>
> [foo]: /url
</code></pre>
</li>
<li>
<p>If there are multiple definitions for the same reference, which takes
precedence?</p>
<pre><code class="language-markdown">[foo]: /url1
[foo]: /url2
[foo][]
</code></pre>
</li>
</ol>
<p>In the absence of a spec, early implementers consulted <code>Markdown.pl</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.</p>
<p>Because there is no unambiguous spec, implementations have diverged
considerably. 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>
<h2 id="about-this-document" href="#about-this-document" class="definition">
<span class="number">1.3</span>About this document
</h2>
<p>This document attempts to specify Markdown syntax unambiguously.
It contains many examples with side-by-side Markdown and
HTML. These are intended to double as conformance tests. An
accompanying script <code>spec_tests.py</code> can be used to run the tests
against any Markdown program:</p>
<pre><code>python test/spec_tests.py --spec spec.txt --program PROGRAM
</code></pre>
<p>Since this document describes how Markdown is to be parsed into
an abstract syntax tree, it would have made sense to use an abstract
representation of the syntax tree instead of HTML. But HTML is capable
of representing the structural distinctions we need to make, and the
choice of HTML for the tests makes it possible to run the tests against
an implementation without writing an abstract syntax tree renderer.</p>
<p>This document is generated from a text file, <code>spec.txt</code>, written
in Markdown with a small extension for the side-by-side tests.
The script <code>tools/makespec.py</code> can be used to convert <code>spec.txt</code> into
HTML or CommonMark (which can then be converted into other formats).</p>
<p>In the examples, the <code>→</code> character is used to represent tabs.</p>
<h1 id="preliminaries" href="#preliminaries" class="definition">
<span class="number">2</span>Preliminaries
</h1>
<h2 id="characters-and-lines" href="#characters-and-lines" class="definition">
<span class="number">2.1</span>Characters and lines
</h2>
<p>Any sequence of <a href="#character">characters</a> is a valid CommonMark
document.</p>
<p>A <a id="character" href="#character" class="definition">character</a> is a Unicode code point. Although some
code points (for example, combining accents) do not correspond to
characters in an intuitive sense, all code points count as characters
for purposes of this spec.</p>
<p>This spec does not specify an encoding; it thinks of lines as composed
of <a href="#character">characters</a> rather than bytes. A conforming parser may be limited
to a certain encoding.</p>
<p>A <a id="line" href="#line" class="definition">line</a> is a sequence of zero or more <a href="#character">characters</a>
other than newline (<code>U+000A</code>) or carriage return (<code>U+000D</code>),
followed by a <a href="#line-ending">line ending</a> or by the end of file.</p>
<p>A <a id="line-ending" href="#line-ending" class="definition">line ending</a> is a newline (<code>U+000A</code>), a carriage return
(<code>U+000D</code>) not followed by a newline, or a carriage return and a
following newline.</p>
<p>A line containing no characters, or a line containing only spaces
(<code>U+0020</code>) or tabs (<code>U+0009</code>), is called a <a id="blank-line" href="#blank-line" class="definition">blank line</a>.</p>
<p>The following definitions of character classes will be used in this spec:</p>
<p>A <a id="whitespace-character" href="#whitespace-character" class="definition">whitespace character</a> is a space
(<code>U+0020</code>), tab (<code>U+0009</code>), newline (<code>U+000A</code>), line tabulation (<code>U+000B</code>),
form feed (<code>U+000C</code>), or carriage return (<code>U+000D</code>).</p>
<p><a id="whitespace" href="#whitespace" class="definition">Whitespace</a> is a sequence of one or more <a href="#whitespace-character">whitespace
characters</a>.</p>
<p>A <a id="unicode-whitespace-character" href="#unicode-whitespace-character" class="definition">Unicode whitespace character</a> is
any code point in the Unicode <code>Zs</code> class, or a tab (<code>U+0009</code>),
carriage return (<code>U+000D</code>), newline (<code>U+000A</code>), or form feed
(<code>U+000C</code>).</p>
<p><a id="unicode-whitespace" href="#unicode-whitespace" class="definition">Unicode whitespace</a> is a sequence of one
or more <a href="#unicode-whitespace-character">Unicode whitespace characters</a>.</p>
<p>A <a id="space" href="#space" class="definition">space</a> is <code>U+0020</code>.</p>
<p>A <a id="non-whitespace-character" href="#non-whitespace-character" class="definition">non-whitespace character</a> is any character
that is not a <a href="#whitespace-character">whitespace character</a>.</p>
<p>An <a id="ascii-punctuation-character" href="#ascii-punctuation-character" class="definition">ASCII punctuation character</a>
is <code>!</code>, <code>"</code>, <code>#</code>, <code>$</code>, <code>%</code>, <code>&</code>, <code>'</code>, <code>(</code>, <code>)</code>,
<code>*</code>, <code>+</code>, <code>,</code>, <code>-</code>, <code>.</code>, <code>/</code>, <code>:</code>, <code>;</code>, <code><</code>, <code>=</code>, <code>></code>, <code>?</code>, <code>@</code>,
<code>[</code>, <code>\</code>, <code>]</code>, <code>^</code>, <code>_</code>, <code>`</code>, <code>{</code>, <code>|</code>, <code>}</code>, or <code>~</code>.</p>
<p>A <a id="punctuation-character" href="#punctuation-character" class="definition">punctuation character</a> is an <a href="#ascii-punctuation-character">ASCII
punctuation character</a> or anything in
the Unicode classes <code>Pc</code>, <code>Pd</code>, <code>Pe</code>, <code>Pf</code>, <code>Pi</code>, <code>Po</code>, or <code>Ps</code>.</p>
<h2 id="tabs" href="#tabs" class="definition">
<span class="number">2.2</span>Tabs
</h2>
<p>Tabs in lines are not expanded to <a href="#space">spaces</a>. However,
in contexts where whitespace helps to define block structure,
tabs behave as if they were replaced by spaces with a tab stop
of 4 characters.</p>
<p>Thus, for example, a tab can be used instead of four spaces
in an indented code block. (Note, however, that internal
tabs are passed through as literal tabs, not expanded to
spaces.)</p>
<div class="example" id="example-1">
<div class="examplenum">
<a href="#example-1">Example 1</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">→foo→baz→→bim
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><pre><code>foo→baz→→bim
</code></pre>
</code></pre>
</div>
</div>
<div class="example" id="example-2">
<div class="examplenum">
<a href="#example-2">Example 2</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span><span class="space"> </span>→foo→baz→→bim
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><pre><code>foo→baz→→bim
</code></pre>
</code></pre>
</div>
</div>
<div class="example" id="example-3">
<div class="examplenum">
<a href="#example-3">Example 3</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span>a→a
<span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span>ὐ→a
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><pre><code>a→a
ὐ→a
</code></pre>
</code></pre>
</div>
</div>
<p>In the following example, a continuation paragraph of a list
item is indented with a tab; this has exactly the same effect
as indentation with four spaces would:</p>
<div class="example" id="example-4">
<div class="examplenum">
<a href="#example-4">Example 4</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span><span class="space"> </span>-<span class="space"> </span>foo
→bar
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><ul>
<li>
<p>foo</p>
<p>bar</p>
</li>
</ul>
</code></pre>
</div>
</div>
<div class="example" id="example-5">
<div class="examplenum">
<a href="#example-5">Example 5</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">-<span class="space"> </span>foo
→→bar
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><ul>
<li>
<p>foo</p>
<pre><code><span class="space"> </span><span class="space"> </span>bar
</code></pre>
</li>
</ul>
</code></pre>
</div>
</div>
<p>Normally the <code>></code> that begins a block quote may be followed
optionally by a space, which is not considered part of the
content. In the following case <code>></code> is followed by a tab,
which is treated as if it were expanded into spaces.
Since one of theses spaces is considered part of the
delimiter, <code>foo</code> is considered to be indented six spaces
inside the block quote context, so we get an indented
code block starting with two spaces.</p>
<div class="example" id="example-6">
<div class="examplenum">
<a href="#example-6">Example 6</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">>→→foo
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><blockquote>
<pre><code><span class="space"> </span><span class="space"> </span>foo
</code></pre>
</blockquote>
</code></pre>
</div>
</div>
<div class="example" id="example-7">
<div class="examplenum">
<a href="#example-7">Example 7</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">-→→foo
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><ul>
<li>
<pre><code><span class="space"> </span><span class="space"> </span>foo
</code></pre>
</li>
</ul>
</code></pre>
</div>
</div>
<div class="example" id="example-8">
<div class="examplenum">
<a href="#example-8">Example 8</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span>foo
→bar
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><pre><code>foo
bar
</code></pre>
</code></pre>
</div>
</div>
<div class="example" id="example-9">
<div class="examplenum">
<a href="#example-9">Example 9</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span>-<span class="space"> </span>foo
<span class="space"> </span><span class="space"> </span><span class="space"> </span>-<span class="space"> </span>bar
→<span class="space"> </span>-<span class="space"> </span>baz
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><ul>
<li>foo
<ul>
<li>bar
<ul>
<li>baz</li>
</ul>
</li>
</ul>
</li>
</ul>
</code></pre>
</div>
</div>
<div class="example" id="example-10">
<div class="examplenum">
<a href="#example-10">Example 10</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">#→Foo
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><h1>Foo</h1>
</code></pre>
</div>
</div>
<div class="example" id="example-11">
<div class="examplenum">
<a href="#example-11">Example 11</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">*→*→*→
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><hr<span class="space"> </span>/>
</code></pre>
</div>
</div>
<h2 id="insecure-characters" href="#insecure-characters" class="definition">
<span class="number">2.3</span>Insecure characters
</h2>
<p>For security reasons, the Unicode character <code>U+0000</code> must be replaced
with the REPLACEMENT CHARACTER (<code>U+FFFD</code>).</p>
<h1 id="blocks-and-inlines" href="#blocks-and-inlines" class="definition">
<span class="number">3</span>Blocks and inlines
</h1>
<p>We can think of a document as a sequence of
<a id="blocks" href="#blocks" class="definition">blocks</a>—structural elements like paragraphs, block
quotations, lists, headings, rules, and code blocks. Some blocks (like
block quotes and list items) contain other blocks; others (like
headings and paragraphs) contain <a id="inline" href="#inline" class="definition">inline</a> content—text,
links, emphasized text, images, code, and so on.</p>
<h2 id="precedence" href="#precedence" class="definition">
<span class="number">3.1</span>Precedence
</h2>
<p>Indicators of block structure always take precedence over indicators
of inline structure. So, for example, the following is a list with
two items, not a list with one item containing a code span:</p>
<div class="example" id="example-12">
<div class="examplenum">
<a href="#example-12">Example 12</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">-<span class="space"> </span>`one
-<span class="space"> </span>two`
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><ul>
<li>`one</li>
<li>two`</li>
</ul>
</code></pre>
</div>
</div>
<p>This means that parsing can proceed in two steps: first, the block
structure of the document can be discerned; second, text lines inside
paragraphs, headings, and other block constructs can be parsed for inline
structure. The second step requires information about link reference
definitions that will be available only at the end of the first
step. Note that the first step requires processing lines in sequence,
but the second can be parallelized, since the inline parsing of
one block element does not affect the inline parsing of any other.</p>
<h2 id="container-blocks-and-leaf-blocks" href="#container-blocks-and-leaf-blocks" class="definition">
<span class="number">3.2</span>Container blocks and leaf blocks
</h2>
<p>We can divide blocks into two types:
<a id="container-block" href="#container-block" class="definition">container block</a>s,
which can contain other blocks, and <a id="leaf-block" href="#leaf-block" class="definition">leaf block</a>s,
which cannot.</p>
<h1 id="leaf-blocks" href="#leaf-blocks" class="definition">
<span class="number">4</span>Leaf blocks
</h1>
<p>This section describes the different kinds of leaf block that make up a
Markdown document.</p>
<h2 id="thematic-breaks" href="#thematic-breaks" class="definition">
<span class="number">4.1</span>Thematic breaks
</h2>
<p>A line consisting of 0-3 spaces of indentation, followed by a sequence
of three or more matching <code>-</code>, <code>_</code>, or <code>*</code> characters, each followed
optionally by any number of spaces, forms a
<a id="thematic-break" href="#thematic-break" class="definition">thematic break</a>.</p>
<div class="example" id="example-13">
<div class="examplenum">
<a href="#example-13">Example 13</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">***
---
___
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><hr<span class="space"> </span>/>
<hr<span class="space"> </span>/>
<hr<span class="space"> </span>/>
</code></pre>
</div>
</div>
<p>Wrong characters:</p>
<div class="example" id="example-14">
<div class="examplenum">
<a href="#example-14">Example 14</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">+++
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><p>+++</p>
</code></pre>
</div>
</div>
<div class="example" id="example-15">
<div class="examplenum">
<a href="#example-15">Example 15</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">===
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><p>===</p>
</code></pre>
</div>
</div>
<p>Not enough characters:</p>
<div class="example" id="example-16">
<div class="examplenum">
<a href="#example-16">Example 16</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">--
**
__
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><p>--
**
__</p>
</code></pre>
</div>
</div>
<p>One to three spaces indent are allowed:</p>
<div class="example" id="example-17">
<div class="examplenum">
<a href="#example-17">Example 17</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span>***
<span class="space"> </span><span class="space"> </span>***
<span class="space"> </span><span class="space"> </span><span class="space"> </span>***
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><hr<span class="space"> </span>/>
<hr<span class="space"> </span>/>
<hr<span class="space"> </span>/>
</code></pre>
</div>
</div>
<p>Four spaces is too many:</p>
<div class="example" id="example-18">
<div class="examplenum">
<a href="#example-18">Example 18</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span>***
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><pre><code>***
</code></pre>
</code></pre>
</div>
</div>
<div class="example" id="example-19">
<div class="examplenum">
<a href="#example-19">Example 19</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">Foo
<span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span>***
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><p>Foo
***</p>
</code></pre>
</div>
</div>
<p>More than three characters may be used:</p>
<div class="example" id="example-20">
<div class="examplenum">
<a href="#example-20">Example 20</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">_____________________________________
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><hr<span class="space"> </span>/>
</code></pre>
</div>
</div>
<p>Spaces are allowed between the characters:</p>
<div class="example" id="example-21">
<div class="examplenum">
<a href="#example-21">Example 21</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span>-<span class="space"> </span>-<span class="space"> </span>-
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><hr<span class="space"> </span>/>
</code></pre>
</div>
</div>
<div class="example" id="example-22">
<div class="examplenum">
<a href="#example-22">Example 22</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span>**<span class="space"> </span><span class="space"> </span>*<span class="space"> </span>**<span class="space"> </span>*<span class="space"> </span>**<span class="space"> </span>*<span class="space"> </span>**
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><hr<span class="space"> </span>/>
</code></pre>
</div>
</div>
<div class="example" id="example-23">
<div class="examplenum">
<a href="#example-23">Example 23</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">-<span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span>-<span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span>-<span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span>-
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><hr<span class="space"> </span>/>
</code></pre>
</div>
</div>
<p>Spaces are allowed at the end:</p>
<div class="example" id="example-24">
<div class="examplenum">
<a href="#example-24">Example 24</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">-<span class="space"> </span>-<span class="space"> </span>-<span class="space"> </span>-<span class="space"> </span><span class="space"> </span><span class="space"> </span><span class="space"> </span>
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><hr<span class="space"> </span>/>
</code></pre>
</div>
</div>
<p>However, no other characters may occur in the line:</p>
<div class="example" id="example-25">
<div class="examplenum">
<a href="#example-25">Example 25</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">_<span class="space"> </span>_<span class="space"> </span>_<span class="space"> </span>_<span class="space"> </span>a
a------
---a---
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><p>_<span class="space"> </span>_<span class="space"> </span>_<span class="space"> </span>_<span class="space"> </span>a</p>
<p>a------</p>
<p>---a---</p>
</code></pre>
</div>
</div>
<p>It is required that all of the <a href="#non-whitespace-character">non-whitespace characters</a> be the same.
So, this is not a thematic break:</p>
<div class="example" id="example-26">
<div class="examplenum">
<a href="#example-26">Example 26</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown"><span class="space"> </span>*-*
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><p><em>-</em></p>
</code></pre>
</div>
</div>
<p>Thematic breaks do not need blank lines before or after:</p>
<div class="example" id="example-27">
<div class="examplenum">
<a href="#example-27">Example 27</a><a class="dingus" title="open in interactive dingus">Try It</a>
</div>
<div class="column">
<pre><code class="language-markdown">-<span class="space"> </span>foo
***
-<span class="space"> </span>bar
</code></pre>
</div>
<div class="column">
<pre><code class="language-html"><ul>
<li>foo</li>
</ul>
<hr<span class="space"> </span>/>