Updated CommonMark specification, used only for tests
[simantics/platform.git] / tests / org.simantics.scl.compiler.tests / src / org / simantics / scl / compiler / tests / markdown / spec.txt
1 ---
2 title: CommonMark Spec
3 author: John MacFarlane
4 version: 0.27
5 date: '2016-11-18'
6 license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)'
7 ...
8
9 # Introduction
10
11 ## What is Markdown?
12
13 Markdown is a plain text format for writing structured documents,
14 based on conventions for indicating formatting in email
15 and usenet posts.  It was developed by John Gruber (with
16 help from Aaron Swartz) and released in 2004 in the form of a
17 [syntax description](http://daringfireball.net/projects/markdown/syntax)
18 and a Perl script (`Markdown.pl`) for converting Markdown to
19 HTML.  In the next decade, dozens of implementations were
20 developed in many languages.  Some extended the original
21 Markdown syntax with conventions for footnotes, tables, and
22 other document elements.  Some allowed Markdown documents to be
23 rendered in formats other than HTML.  Websites like Reddit,
24 StackOverflow, and GitHub had millions of people using Markdown.
25 And Markdown started to be used beyond the web, to author books,
26 articles, slide shows, letters, and lecture notes.
27
28 What distinguishes Markdown from many other lightweight markup
29 syntaxes, which are often easier to write, is its readability.
30 As Gruber writes:
31
32 > The overriding design goal for Markdown's formatting syntax is
33 > to make it as readable as possible. The idea is that a
34 > Markdown-formatted document should be publishable as-is, as
35 > plain text, without looking like it's been marked up with tags
36 > or formatting instructions.
37 > (<http://daringfireball.net/projects/markdown/>)
38
39 The point can be illustrated by comparing a sample of
40 [AsciiDoc](http://www.methods.co.nz/asciidoc/) with
41 an equivalent sample of Markdown.  Here is a sample of
42 AsciiDoc from the AsciiDoc manual:
43
44 ```
45 1. List item one.
46 +
47 List item one continued with a second paragraph followed by an
48 Indented block.
49 +
50 .................
51 $ ls *.sh
52 $ mv *.sh ~/tmp
53 .................
54 +
55 List item continued with a third paragraph.
56
57 2. List item two continued with an open block.
58 +
59 --
60 This paragraph is part of the preceding list item.
61
62 a. This list is nested and does not require explicit item
63 continuation.
64 +
65 This paragraph is part of the preceding list item.
66
67 b. List item b.
68
69 This paragraph belongs to item two of the outer list.
70 --
71 ```
72
73 And here is the equivalent in Markdown:
74 ```
75 1.  List item one.
76
77     List item one continued with a second paragraph followed by an
78     Indented block.
79
80         $ ls *.sh
81         $ mv *.sh ~/tmp
82
83     List item continued with a third paragraph.
84
85 2.  List item two continued with an open block.
86
87     This paragraph is part of the preceding list item.
88
89     1. This list is nested and does not require explicit item continuation.
90
91        This paragraph is part of the preceding list item.
92
93     2. List item b.
94
95     This paragraph belongs to item two of the outer list.
96 ```
97
98 The AsciiDoc version is, arguably, easier to write. You don't need
99 to worry about indentation.  But the Markdown version is much easier
100 to read.  The nesting of list items is apparent to the eye in the
101 source, not just in the processed document.
102
103 ## Why is a spec needed?
104
105 John Gruber's [canonical description of Markdown's
106 syntax](http://daringfireball.net/projects/markdown/syntax)
107 does not specify the syntax unambiguously.  Here are some examples of
108 questions it does not answer:
109
110 1.  How much indentation is needed for a sublist?  The spec says that
111     continuation paragraphs need to be indented four spaces, but is
112     not fully explicit about sublists.  It is natural to think that
113     they, too, must be indented four spaces, but `Markdown.pl` does
114     not require that.  This is hardly a "corner case," and divergences
115     between implementations on this issue often lead to surprises for
116     users in real documents. (See [this comment by John
117     Gruber](http://article.gmane.org/gmane.text.markdown.general/1997).)
118
119 2.  Is a blank line needed before a block quote or heading?
120     Most implementations do not require the blank line.  However,
121     this can lead to unexpected results in hard-wrapped text, and
122     also to ambiguities in parsing (note that some implementations
123     put the heading inside the blockquote, while others do not).
124     (John Gruber has also spoken [in favor of requiring the blank
125     lines](http://article.gmane.org/gmane.text.markdown.general/2146).)
126
127 3.  Is a blank line needed before an indented code block?
128     (`Markdown.pl` requires it, but this is not mentioned in the
129     documentation, and some implementations do not require it.)
130
131     ``` markdown
132     paragraph
133         code?
134     ```
135
136 4.  What is the exact rule for determining when list items get
137     wrapped in `<p>` tags?  Can a list be partially "loose" and partially
138     "tight"?  What should we do with a list like this?
139
140     ``` markdown
141     1. one
142
143     2. two
144     3. three
145     ```
146
147     Or this?
148
149     ``` markdown
150     1.  one
151         - a
152
153         - b
154     2.  two
155     ```
156
157     (There are some relevant comments by John Gruber
158     [here](http://article.gmane.org/gmane.text.markdown.general/2554).)
159
160 5.  Can list markers be indented?  Can ordered list markers be right-aligned?
161
162     ``` markdown
163      8. item 1
164      9. item 2
165     10. item 2a
166     ```
167
168 6.  Is this one list with a thematic break in its second item,
169     or two lists separated by a thematic break?
170
171     ``` markdown
172     * a
173     * * * * *
174     * b
175     ```
176
177 7.  When list markers change from numbers to bullets, do we have
178     two lists or one?  (The Markdown syntax description suggests two,
179     but the perl scripts and many other implementations produce one.)
180
181     ``` markdown
182     1. fee
183     2. fie
184     -  foe
185     -  fum
186     ```
187
188 8.  What are the precedence rules for the markers of inline structure?
189     For example, is the following a valid link, or does the code span
190     take precedence ?
191
192     ``` markdown
193     [a backtick (`)](/url) and [another backtick (`)](/url).
194     ```
195
196 9.  What are the precedence rules for markers of emphasis and strong
197     emphasis?  For example, how should the following be parsed?
198
199     ``` markdown
200     *foo *bar* baz*
201     ```
202
203 10. What are the precedence rules between block-level and inline-level
204     structure?  For example, how should the following be parsed?
205
206     ``` markdown
207     - `a long code span can contain a hyphen like this
208       - and it can screw things up`
209     ```
210
211 11. Can list items include section headings?  (`Markdown.pl` does not
212     allow this, but does allow blockquotes to include headings.)
213
214     ``` markdown
215     - # Heading
216     ```
217
218 12. Can list items be empty?
219
220     ``` markdown
221     * a
222     *
223     * b
224     ```
225
226 13. Can link references be defined inside block quotes or list items?
227
228     ``` markdown
229     > Blockquote [foo].
230     >
231     > [foo]: /url
232     ```
233
234 14. If there are multiple definitions for the same reference, which takes
235     precedence?
236
237     ``` markdown
238     [foo]: /url1
239     [foo]: /url2
240
241     [foo][]
242     ```
243
244 In the absence of a spec, early implementers consulted `Markdown.pl`
245 to resolve these ambiguities.  But `Markdown.pl` was quite buggy, and
246 gave manifestly bad results in many cases, so it was not a
247 satisfactory replacement for a spec.
248
249 Because there is no unambiguous spec, implementations have diverged
250 considerably.  As a result, users are often surprised to find that
251 a document that renders one way on one system (say, a github wiki)
252 renders differently on another (say, converting to docbook using
253 pandoc).  To make matters worse, because nothing in Markdown counts
254 as a "syntax error," the divergence often isn't discovered right away.
255
256 ## About this document
257
258 This document attempts to specify Markdown syntax unambiguously.
259 It contains many examples with side-by-side Markdown and
260 HTML.  These are intended to double as conformance tests.  An
261 accompanying script `spec_tests.py` can be used to run the tests
262 against any Markdown program:
263
264     python test/spec_tests.py --spec spec.txt --program PROGRAM
265
266 Since this document describes how Markdown is to be parsed into
267 an abstract syntax tree, it would have made sense to use an abstract
268 representation of the syntax tree instead of HTML.  But HTML is capable
269 of representing the structural distinctions we need to make, and the
270 choice of HTML for the tests makes it possible to run the tests against
271 an implementation without writing an abstract syntax tree renderer.
272
273 This document is generated from a text file, `spec.txt`, written
274 in Markdown with a small extension for the side-by-side tests.
275 The script `tools/makespec.py` can be used to convert `spec.txt` into
276 HTML or CommonMark (which can then be converted into other formats).
277
278 In the examples, the `→` character is used to represent tabs.
279
280 # Preliminaries
281
282 ## Characters and lines
283
284 Any sequence of [characters] is a valid CommonMark
285 document.
286
287 A [character](@) is a Unicode code point.  Although some
288 code points (for example, combining accents) do not correspond to
289 characters in an intuitive sense, all code points count as characters
290 for purposes of this spec.
291
292 This spec does not specify an encoding; it thinks of lines as composed
293 of [characters] rather than bytes.  A conforming parser may be limited
294 to a certain encoding.
295
296 A [line](@) is a sequence of zero or more [characters]
297 other than newline (`U+000A`) or carriage return (`U+000D`),
298 followed by a [line ending] or by the end of file.
299
300 A [line ending](@) is a newline (`U+000A`), a carriage return
301 (`U+000D`) not followed by a newline, or a carriage return and a
302 following newline.
303
304 A line containing no characters, or a line containing only spaces
305 (`U+0020`) or tabs (`U+0009`), is called a [blank line](@).
306
307 The following definitions of character classes will be used in this spec:
308
309 A [whitespace character](@) is a space
310 (`U+0020`), tab (`U+0009`), newline (`U+000A`), line tabulation (`U+000B`),
311 form feed (`U+000C`), or carriage return (`U+000D`).
312
313 [Whitespace](@) is a sequence of one or more [whitespace
314 characters].
315
316 A [Unicode whitespace character](@) is
317 any code point in the Unicode `Zs` general category, or a tab (`U+0009`),
318 carriage return (`U+000D`), newline (`U+000A`), or form feed
319 (`U+000C`).
320
321 [Unicode whitespace](@) is a sequence of one
322 or more [Unicode whitespace characters].
323
324 A [space](@) is `U+0020`.
325
326 A [non-whitespace character](@) is any character
327 that is not a [whitespace character].
328
329 An [ASCII punctuation character](@)
330 is `!`, `"`, `#`, `$`, `%`, `&`, `'`, `(`, `)`,
331 `*`, `+`, `,`, `-`, `.`, `/`, `:`, `;`, `<`, `=`, `>`, `?`, `@`,
332 `[`, `\`, `]`, `^`, `_`, `` ` ``, `{`, `|`, `}`, or `~`.
333
334 A [punctuation character](@) is an [ASCII
335 punctuation character] or anything in
336 the general Unicode categories  `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`.
337
338 ## Tabs
339
340 Tabs in lines are not expanded to [spaces].  However,
341 in contexts where whitespace helps to define block structure,
342 tabs behave as if they were replaced by spaces with a tab stop
343 of 4 characters.
344
345 Thus, for example, a tab can be used instead of four spaces
346 in an indented code block.  (Note, however, that internal
347 tabs are passed through as literal tabs, not expanded to
348 spaces.)
349
350 ```````````````````````````````` example
351 →foo→baz→→bim
352 .
353 <pre><code>foo→baz→→bim
354 </code></pre>
355 ````````````````````````````````
356
357 ```````````````````````````````` example
358   →foo→baz→→bim
359 .
360 <pre><code>foo→baz→→bim
361 </code></pre>
362 ````````````````````````````````
363
364 ```````````````````````````````` example
365     a→a
366     ὐ→a
367 .
368 <pre><code>a→a
369 ὐ→a
370 </code></pre>
371 ````````````````````````````````
372
373 In the following example, a continuation paragraph of a list
374 item is indented with a tab; this has exactly the same effect
375 as indentation with four spaces would:
376
377 ```````````````````````````````` example
378   - foo
379
380 →bar
381 .
382 <ul>
383 <li>
384 <p>foo</p>
385 <p>bar</p>
386 </li>
387 </ul>
388 ````````````````````````````````
389
390 ```````````````````````````````` example
391 - foo
392
393 →→bar
394 .
395 <ul>
396 <li>
397 <p>foo</p>
398 <pre><code>  bar
399 </code></pre>
400 </li>
401 </ul>
402 ````````````````````````````````
403
404 Normally the `>` that begins a block quote may be followed
405 optionally by a space, which is not considered part of the
406 content.  In the following case `>` is followed by a tab,
407 which is treated as if it were expanded into three spaces.
408 Since one of these spaces is considered part of the
409 delimiter, `foo` is considered to be indented six spaces
410 inside the block quote context, so we get an indented
411 code block starting with two spaces.
412
413 ```````````````````````````````` example
414 >→→foo
415 .
416 <blockquote>
417 <pre><code>  foo
418 </code></pre>
419 </blockquote>
420 ````````````````````````````````
421
422 ```````````````````````````````` example
423 -→→foo
424 .
425 <ul>
426 <li>
427 <pre><code>  foo
428 </code></pre>
429 </li>
430 </ul>
431 ````````````````````````````````
432
433
434 ```````````````````````````````` example
435     foo
436 →bar
437 .
438 <pre><code>foo
439 bar
440 </code></pre>
441 ````````````````````````````````
442
443 ```````````````````````````````` example
444  - foo
445    - bar
446 → - baz
447 .
448 <ul>
449 <li>foo
450 <ul>
451 <li>bar
452 <ul>
453 <li>baz</li>
454 </ul>
455 </li>
456 </ul>
457 </li>
458 </ul>
459 ````````````````````````````````
460
461 ```````````````````````````````` example
462 #→Foo
463 .
464 <h1>Foo</h1>
465 ````````````````````````````````
466
467 ```````````````````````````````` example
468 *→*→*→
469 .
470 <hr />
471 ````````````````````````````````
472
473
474 ## Insecure characters
475
476 For security reasons, the Unicode character `U+0000` must be replaced
477 with the REPLACEMENT CHARACTER (`U+FFFD`).
478
479 # Blocks and inlines
480
481 We can think of a document as a sequence of
482 [blocks](@)---structural elements like paragraphs, block
483 quotations, lists, headings, rules, and code blocks.  Some blocks (like
484 block quotes and list items) contain other blocks; others (like
485 headings and paragraphs) contain [inline](@) content---text,
486 links, emphasized text, images, code spans, and so on.
487
488 ## Precedence
489
490 Indicators of block structure always take precedence over indicators
491 of inline structure.  So, for example, the following is a list with
492 two items, not a list with one item containing a code span:
493
494 ```````````````````````````````` example
495 - `one
496 - two`
497 .
498 <ul>
499 <li>`one</li>
500 <li>two`</li>
501 </ul>
502 ````````````````````````````````
503
504
505 This means that parsing can proceed in two steps:  first, the block
506 structure of the document can be discerned; second, text lines inside
507 paragraphs, headings, and other block constructs can be parsed for inline
508 structure.  The second step requires information about link reference
509 definitions that will be available only at the end of the first
510 step.  Note that the first step requires processing lines in sequence,
511 but the second can be parallelized, since the inline parsing of
512 one block element does not affect the inline parsing of any other.
513
514 ## Container blocks and leaf blocks
515
516 We can divide blocks into two types:
517 [container block](@)s,
518 which can contain other blocks, and [leaf block](@)s,
519 which cannot.
520
521 # Leaf blocks
522
523 This section describes the different kinds of leaf block that make up a
524 Markdown document.
525
526 ## Thematic breaks
527
528 A line consisting of 0-3 spaces of indentation, followed by a sequence
529 of three or more matching `-`, `_`, or `*` characters, each followed
530 optionally by any number of spaces, forms a
531 [thematic break](@).
532
533 ```````````````````````````````` example
534 ***
535 ---
536 ___
537 .
538 <hr />
539 <hr />
540 <hr />
541 ````````````````````````````````
542
543
544 Wrong characters:
545
546 ```````````````````````````````` example
547 +++
548 .
549 <p>+++</p>
550 ````````````````````````````````
551
552
553 ```````````````````````````````` example
554 ===
555 .
556 <p>===</p>
557 ````````````````````````````````
558
559
560 Not enough characters:
561
562 ```````````````````````````````` example
563 --
564 **
565 __
566 .
567 <p>--
568 **
569 __</p>
570 ````````````````````````````````
571
572
573 One to three spaces indent are allowed:
574
575 ```````````````````````````````` example
576  ***
577   ***
578    ***
579 .
580 <hr />
581 <hr />
582 <hr />
583 ````````````````````````````````
584
585
586 Four spaces is too many:
587
588 ```````````````````````````````` example
589     ***
590 .
591 <pre><code>***
592 </code></pre>
593 ````````````````````````````````
594
595
596 ```````````````````````````````` example
597 Foo
598     ***
599 .
600 <p>Foo
601 ***</p>
602 ````````````````````````````````
603
604
605 More than three characters may be used:
606
607 ```````````````````````````````` example
608 _____________________________________
609 .
610 <hr />
611 ````````````````````````````````
612
613
614 Spaces are allowed between the characters:
615
616 ```````````````````````````````` example
617  - - -
618 .
619 <hr />
620 ````````````````````````````````
621
622
623 ```````````````````````````````` example
624  **  * ** * ** * **
625 .
626 <hr />
627 ````````````````````````````````
628
629
630 ```````````````````````````````` example
631 -     -      -      -
632 .
633 <hr />
634 ````````````````````````````````
635
636
637 Spaces are allowed at the end:
638
639 ```````````````````````````````` example
640 - - - -    
641 .
642 <hr />
643 ````````````````````````````````
644
645
646 However, no other characters may occur in the line:
647
648 ```````````````````````````````` example
649 _ _ _ _ a
650
651 a------
652
653 ---a---
654 .
655 <p>_ _ _ _ a</p>
656 <p>a------</p>
657 <p>---a---</p>
658 ````````````````````````````````
659
660
661 It is required that all of the [non-whitespace characters] be the same.
662 So, this is not a thematic break:
663
664 ```````````````````````````````` example
665  *-*
666 .
667 <p><em>-</em></p>
668 ````````````````````````````````
669
670
671 Thematic breaks do not need blank lines before or after:
672
673 ```````````````````````````````` example
674 - foo
675 ***
676 - bar
677 .
678 <ul>
679 <li>foo</li>
680 </ul>
681 <hr />
682 <ul>
683 <li>bar</li>
684 </ul>
685 ````````````````````````````````
686
687
688 Thematic breaks can interrupt a paragraph:
689
690 ```````````````````````````````` example
691 Foo
692 ***
693 bar
694 .
695 <p>Foo</p>
696 <hr />
697 <p>bar</p>
698 ````````````````````````````````
699
700
701 If a line of dashes that meets the above conditions for being a
702 thematic break could also be interpreted as the underline of a [setext
703 heading], the interpretation as a
704 [setext heading] takes precedence. Thus, for example,
705 this is a setext heading, not a paragraph followed by a thematic break:
706
707 ```````````````````````````````` example
708 Foo
709 ---
710 bar
711 .
712 <h2>Foo</h2>
713 <p>bar</p>
714 ````````````````````````````````
715
716
717 When both a thematic break and a list item are possible
718 interpretations of a line, the thematic break takes precedence:
719
720 ```````````````````````````````` example
721 * Foo
722 * * *
723 * Bar
724 .
725 <ul>
726 <li>Foo</li>
727 </ul>
728 <hr />
729 <ul>
730 <li>Bar</li>
731 </ul>
732 ````````````````````````````````
733
734
735 If you want a thematic break in a list item, use a different bullet:
736
737 ```````````````````````````````` example
738 - Foo
739 - * * *
740 .
741 <ul>
742 <li>Foo</li>
743 <li>
744 <hr />
745 </li>
746 </ul>
747 ````````````````````````````````
748
749
750 ## ATX headings
751
752 An [ATX heading](@)
753 consists of a string of characters, parsed as inline content, between an
754 opening sequence of 1--6 unescaped `#` characters and an optional
755 closing sequence of any number of unescaped `#` characters.
756 The opening sequence of `#` characters must be followed by a
757 [space] or by the end of line. The optional closing sequence of `#`s must be
758 preceded by a [space] and may be followed by spaces only.  The opening
759 `#` character may be indented 0-3 spaces.  The raw contents of the
760 heading are stripped of leading and trailing spaces before being parsed
761 as inline content.  The heading level is equal to the number of `#`
762 characters in the opening sequence.
763
764 Simple headings:
765
766 ```````````````````````````````` example
767 # foo
768 ## foo
769 ### foo
770 #### foo
771 ##### foo
772 ###### foo
773 .
774 <h1>foo</h1>
775 <h2>foo</h2>
776 <h3>foo</h3>
777 <h4>foo</h4>
778 <h5>foo</h5>
779 <h6>foo</h6>
780 ````````````````````````````````
781
782
783 More than six `#` characters is not a heading:
784
785 ```````````````````````````````` example
786 ####### foo
787 .
788 <p>####### foo</p>
789 ````````````````````````````````
790
791
792 At least one space is required between the `#` characters and the
793 heading's contents, unless the heading is empty.  Note that many
794 implementations currently do not require the space.  However, the
795 space was required by the
796 [original ATX implementation](http://www.aaronsw.com/2002/atx/atx.py),
797 and it helps prevent things like the following from being parsed as
798 headings:
799
800 ```````````````````````````````` example
801 #5 bolt
802
803 #hashtag
804 .
805 <p>#5 bolt</p>
806 <p>#hashtag</p>
807 ````````````````````````````````
808
809
810 This is not a heading, because the first `#` is escaped:
811
812 ```````````````````````````````` example
813 \## foo
814 .
815 <p>## foo</p>
816 ````````````````````````````````
817
818
819 Contents are parsed as inlines:
820
821 ```````````````````````````````` example
822 # foo *bar* \*baz\*
823 .
824 <h1>foo <em>bar</em> *baz*</h1>
825 ````````````````````````````````
826
827
828 Leading and trailing blanks are ignored in parsing inline content:
829
830 ```````````````````````````````` example
831 #                  foo                     
832 .
833 <h1>foo</h1>
834 ````````````````````````````````
835
836
837 One to three spaces indentation are allowed:
838
839 ```````````````````````````````` example
840  ### foo
841   ## foo
842    # foo
843 .
844 <h3>foo</h3>
845 <h2>foo</h2>
846 <h1>foo</h1>
847 ````````````````````````````````
848
849
850 Four spaces are too much:
851
852 ```````````````````````````````` example
853     # foo
854 .
855 <pre><code># foo
856 </code></pre>
857 ````````````````````````````````
858
859
860 ```````````````````````````````` example
861 foo
862     # bar
863 .
864 <p>foo
865 # bar</p>
866 ````````````````````````````````
867
868
869 A closing sequence of `#` characters is optional:
870
871 ```````````````````````````````` example
872 ## foo ##
873   ###   bar    ###
874 .
875 <h2>foo</h2>
876 <h3>bar</h3>
877 ````````````````````````````````
878
879
880 It need not be the same length as the opening sequence:
881
882 ```````````````````````````````` example
883 # foo ##################################
884 ##### foo ##
885 .
886 <h1>foo</h1>
887 <h5>foo</h5>
888 ````````````````````````````````
889
890
891 Spaces are allowed after the closing sequence:
892
893 ```````````````````````````````` example
894 ### foo ###     
895 .
896 <h3>foo</h3>
897 ````````````````````````````````
898
899
900 A sequence of `#` characters with anything but [spaces] following it
901 is not a closing sequence, but counts as part of the contents of the
902 heading:
903
904 ```````````````````````````````` example
905 ### foo ### b
906 .
907 <h3>foo ### b</h3>
908 ````````````````````````````````
909
910
911 The closing sequence must be preceded by a space:
912
913 ```````````````````````````````` example
914 # foo#
915 .
916 <h1>foo#</h1>
917 ````````````````````````````````
918
919
920 Backslash-escaped `#` characters do not count as part
921 of the closing sequence:
922
923 ```````````````````````````````` example
924 ### foo \###
925 ## foo #\##
926 # foo \#
927 .
928 <h3>foo ###</h3>
929 <h2>foo ###</h2>
930 <h1>foo #</h1>
931 ````````````````````````````````
932
933
934 ATX headings need not be separated from surrounding content by blank
935 lines, and they can interrupt paragraphs:
936
937 ```````````````````````````````` example
938 ****
939 ## foo
940 ****
941 .
942 <hr />
943 <h2>foo</h2>
944 <hr />
945 ````````````````````````````````
946
947
948 ```````````````````````````````` example
949 Foo bar
950 # baz
951 Bar foo
952 .
953 <p>Foo bar</p>
954 <h1>baz</h1>
955 <p>Bar foo</p>
956 ````````````````````````````````
957
958
959 ATX headings can be empty:
960
961 ```````````````````````````````` example
962 ## 
963 #
964 ### ###
965 .
966 <h2></h2>
967 <h1></h1>
968 <h3></h3>
969 ````````````````````````````````
970
971
972 ## Setext headings
973
974 A [setext heading](@) consists of one or more
975 lines of text, each containing at least one [non-whitespace
976 character], with no more than 3 spaces indentation, followed by
977 a [setext heading underline].  The lines of text must be such
978 that, were they not followed by the setext heading underline,
979 they would be interpreted as a paragraph:  they cannot be
980 interpretable as a [code fence], [ATX heading][ATX headings],
981 [block quote][block quotes], [thematic break][thematic breaks],
982 [list item][list items], or [HTML block][HTML blocks].
983
984 A [setext heading underline](@) is a sequence of
985 `=` characters or a sequence of `-` characters, with no more than 3
986 spaces indentation and any number of trailing spaces.  If a line
987 containing a single `-` can be interpreted as an
988 empty [list items], it should be interpreted this way
989 and not as a [setext heading underline].
990
991 The heading is a level 1 heading if `=` characters are used in
992 the [setext heading underline], and a level 2 heading if `-`
993 characters are used.  The contents of the heading are the result
994 of parsing the preceding lines of text as CommonMark inline
995 content.
996
997 In general, a setext heading need not be preceded or followed by a
998 blank line.  However, it cannot interrupt a paragraph, so when a
999 setext heading comes after a paragraph, a blank line is needed between
1000 them.
1001
1002 Simple examples:
1003
1004 ```````````````````````````````` example
1005 Foo *bar*
1006 =========
1007
1008 Foo *bar*
1009 ---------
1010 .
1011 <h1>Foo <em>bar</em></h1>
1012 <h2>Foo <em>bar</em></h2>
1013 ````````````````````````````````
1014
1015
1016 The content of the header may span more than one line:
1017
1018 ```````````````````````````````` example
1019 Foo *bar
1020 baz*
1021 ====
1022 .
1023 <h1>Foo <em>bar
1024 baz</em></h1>
1025 ````````````````````````````````
1026
1027
1028 The underlining can be any length:
1029
1030 ```````````````````````````````` example
1031 Foo
1032 -------------------------
1033
1034 Foo
1035 =
1036 .
1037 <h2>Foo</h2>
1038 <h1>Foo</h1>
1039 ````````````````````````````````
1040
1041
1042 The heading content can be indented up to three spaces, and need
1043 not line up with the underlining:
1044
1045 ```````````````````````````````` example
1046    Foo
1047 ---
1048
1049   Foo
1050 -----
1051
1052   Foo
1053   ===
1054 .
1055 <h2>Foo</h2>
1056 <h2>Foo</h2>
1057 <h1>Foo</h1>
1058 ````````````````````````````````
1059
1060
1061 Four spaces indent is too much:
1062
1063 ```````````````````````````````` example
1064     Foo
1065     ---
1066
1067     Foo
1068 ---
1069 .
1070 <pre><code>Foo
1071 ---
1072
1073 Foo
1074 </code></pre>
1075 <hr />
1076 ````````````````````````````````
1077
1078
1079 The setext heading underline can be indented up to three spaces, and
1080 may have trailing spaces:
1081
1082 ```````````````````````````````` example
1083 Foo
1084    ----      
1085 .
1086 <h2>Foo</h2>
1087 ````````````````````````````````
1088
1089
1090 Four spaces is too much:
1091
1092 ```````````````````````````````` example
1093 Foo
1094     ---
1095 .
1096 <p>Foo
1097 ---</p>
1098 ````````````````````````````````
1099
1100
1101 The setext heading underline cannot contain internal spaces:
1102
1103 ```````````````````````````````` example
1104 Foo
1105 = =
1106
1107 Foo
1108 --- -
1109 .
1110 <p>Foo
1111 = =</p>
1112 <p>Foo</p>
1113 <hr />
1114 ````````````````````````````````
1115
1116
1117 Trailing spaces in the content line do not cause a line break:
1118
1119 ```````````````````````````````` example
1120 Foo  
1121 -----
1122 .
1123 <h2>Foo</h2>
1124 ````````````````````````````````
1125
1126
1127 Nor does a backslash at the end:
1128
1129 ```````````````````````````````` example
1130 Foo\
1131 ----
1132 .
1133 <h2>Foo\</h2>
1134 ````````````````````````````````
1135
1136
1137 Since indicators of block structure take precedence over
1138 indicators of inline structure, the following are setext headings:
1139
1140 ```````````````````````````````` example
1141 `Foo
1142 ----
1143 `
1144
1145 <a title="a lot
1146 ---
1147 of dashes"/>
1148 .
1149 <h2>`Foo</h2>
1150 <p>`</p>
1151 <h2>&lt;a title=&quot;a lot</h2>
1152 <p>of dashes&quot;/&gt;</p>
1153 ````````````````````````````````
1154
1155
1156 The setext heading underline cannot be a [lazy continuation
1157 line] in a list item or block quote:
1158
1159 ```````````````````````````````` example
1160 > Foo
1161 ---
1162 .
1163 <blockquote>
1164 <p>Foo</p>
1165 </blockquote>
1166 <hr />
1167 ````````````````````````````````
1168
1169
1170 ```````````````````````````````` example
1171 > foo
1172 bar
1173 ===
1174 .
1175 <blockquote>
1176 <p>foo
1177 bar
1178 ===</p>
1179 </blockquote>
1180 ````````````````````````````````
1181
1182
1183 ```````````````````````````````` example
1184 - Foo
1185 ---
1186 .
1187 <ul>
1188 <li>Foo</li>
1189 </ul>
1190 <hr />
1191 ````````````````````````````````
1192
1193
1194 A blank line is needed between a paragraph and a following
1195 setext heading, since otherwise the paragraph becomes part
1196 of the heading's content:
1197
1198 ```````````````````````````````` example
1199 Foo
1200 Bar
1201 ---
1202 .
1203 <h2>Foo
1204 Bar</h2>
1205 ````````````````````````````````
1206
1207
1208 But in general a blank line is not required before or after
1209 setext headings:
1210
1211 ```````````````````````````````` example
1212 ---
1213 Foo
1214 ---
1215 Bar
1216 ---
1217 Baz
1218 .
1219 <hr />
1220 <h2>Foo</h2>
1221 <h2>Bar</h2>
1222 <p>Baz</p>
1223 ````````````````````````````````
1224
1225
1226 Setext headings cannot be empty:
1227
1228 ```````````````````````````````` example
1229
1230 ====
1231 .
1232 <p>====</p>
1233 ````````````````````````````````
1234
1235
1236 Setext heading text lines must not be interpretable as block
1237 constructs other than paragraphs.  So, the line of dashes
1238 in these examples gets interpreted as a thematic break:
1239
1240 ```````````````````````````````` example
1241 ---
1242 ---
1243 .
1244 <hr />
1245 <hr />
1246 ````````````````````````````````
1247
1248
1249 ```````````````````````````````` example
1250 - foo
1251 -----
1252 .
1253 <ul>
1254 <li>foo</li>
1255 </ul>
1256 <hr />
1257 ````````````````````````````````
1258
1259
1260 ```````````````````````````````` example
1261     foo
1262 ---
1263 .
1264 <pre><code>foo
1265 </code></pre>
1266 <hr />
1267 ````````````````````````````````
1268
1269
1270 ```````````````````````````````` example
1271 > foo
1272 -----
1273 .
1274 <blockquote>
1275 <p>foo</p>
1276 </blockquote>
1277 <hr />
1278 ````````````````````````````````
1279
1280
1281 If you want a heading with `> foo` as its literal text, you can
1282 use backslash escapes:
1283
1284 ```````````````````````````````` example
1285 \> foo
1286 ------
1287 .
1288 <h2>&gt; foo</h2>
1289 ````````````````````````````````
1290
1291
1292 **Compatibility note:**  Most existing Markdown implementations
1293 do not allow the text of setext headings to span multiple lines.
1294 But there is no consensus about how to interpret
1295
1296 ``` markdown
1297 Foo
1298 bar
1299 ---
1300 baz
1301 ```
1302
1303 One can find four different interpretations:
1304
1305 1. paragraph "Foo", heading "bar", paragraph "baz"
1306 2. paragraph "Foo bar", thematic break, paragraph "baz"
1307 3. paragraph "Foo bar --- baz"
1308 4. heading "Foo bar", paragraph "baz"
1309
1310 We find interpretation 4 most natural, and interpretation 4
1311 increases the expressive power of CommonMark, by allowing
1312 multiline headings.  Authors who want interpretation 1 can
1313 put a blank line after the first paragraph:
1314
1315 ```````````````````````````````` example
1316 Foo
1317
1318 bar
1319 ---
1320 baz
1321 .
1322 <p>Foo</p>
1323 <h2>bar</h2>
1324 <p>baz</p>
1325 ````````````````````````````````
1326
1327
1328 Authors who want interpretation 2 can put blank lines around
1329 the thematic break,
1330
1331 ```````````````````````````````` example
1332 Foo
1333 bar
1334
1335 ---
1336
1337 baz
1338 .
1339 <p>Foo
1340 bar</p>
1341 <hr />
1342 <p>baz</p>
1343 ````````````````````````````````
1344
1345
1346 or use a thematic break that cannot count as a [setext heading
1347 underline], such as
1348
1349 ```````````````````````````````` example
1350 Foo
1351 bar
1352 * * *
1353 baz
1354 .
1355 <p>Foo
1356 bar</p>
1357 <hr />
1358 <p>baz</p>
1359 ````````````````````````````````
1360
1361
1362 Authors who want interpretation 3 can use backslash escapes:
1363
1364 ```````````````````````````````` example
1365 Foo
1366 bar
1367 \---
1368 baz
1369 .
1370 <p>Foo
1371 bar
1372 ---
1373 baz</p>
1374 ````````````````````````````````
1375
1376
1377 ## Indented code blocks
1378
1379 An [indented code block](@) is composed of one or more
1380 [indented chunks] separated by blank lines.
1381 An [indented chunk](@) is a sequence of non-blank lines,
1382 each indented four or more spaces. The contents of the code block are
1383 the literal contents of the lines, including trailing
1384 [line endings], minus four spaces of indentation.
1385 An indented code block has no [info string].
1386
1387 An indented code block cannot interrupt a paragraph, so there must be
1388 a blank line between a paragraph and a following indented code block.
1389 (A blank line is not needed, however, between a code block and a following
1390 paragraph.)
1391
1392 ```````````````````````````````` example
1393     a simple
1394       indented code block
1395 .
1396 <pre><code>a simple
1397   indented code block
1398 </code></pre>
1399 ````````````````````````````````
1400
1401
1402 If there is any ambiguity between an interpretation of indentation
1403 as a code block and as indicating that material belongs to a [list
1404 item][list items], the list item interpretation takes precedence:
1405
1406 ```````````````````````````````` example
1407   - foo
1408
1409     bar
1410 .
1411 <ul>
1412 <li>
1413 <p>foo</p>
1414 <p>bar</p>
1415 </li>
1416 </ul>
1417 ````````````````````````````````
1418
1419
1420 ```````````````````````````````` example
1421 1.  foo
1422
1423     - bar
1424 .
1425 <ol>
1426 <li>
1427 <p>foo</p>
1428 <ul>
1429 <li>bar</li>
1430 </ul>
1431 </li>
1432 </ol>
1433 ````````````````````````````````
1434
1435
1436
1437 The contents of a code block are literal text, and do not get parsed
1438 as Markdown:
1439
1440 ```````````````````````````````` example
1441     <a/>
1442     *hi*
1443
1444     - one
1445 .
1446 <pre><code>&lt;a/&gt;
1447 *hi*
1448
1449 - one
1450 </code></pre>
1451 ````````````````````````````````
1452
1453
1454 Here we have three chunks separated by blank lines:
1455
1456 ```````````````````````````````` example
1457     chunk1
1458
1459     chunk2
1460   
1461  
1462  
1463     chunk3
1464 .
1465 <pre><code>chunk1
1466
1467 chunk2
1468
1469
1470
1471 chunk3
1472 </code></pre>
1473 ````````````````````````````````
1474
1475
1476 Any initial spaces beyond four will be included in the content, even
1477 in interior blank lines:
1478
1479 ```````````````````````````````` example
1480     chunk1
1481       
1482       chunk2
1483 .
1484 <pre><code>chunk1
1485   
1486   chunk2
1487 </code></pre>
1488 ````````````````````````````````
1489
1490
1491 An indented code block cannot interrupt a paragraph.  (This
1492 allows hanging indents and the like.)
1493
1494 ```````````````````````````````` example
1495 Foo
1496     bar
1497
1498 .
1499 <p>Foo
1500 bar</p>
1501 ````````````````````````````````
1502
1503
1504 However, any non-blank line with fewer than four leading spaces ends
1505 the code block immediately.  So a paragraph may occur immediately
1506 after indented code:
1507
1508 ```````````````````````````````` example
1509     foo
1510 bar
1511 .
1512 <pre><code>foo
1513 </code></pre>
1514 <p>bar</p>
1515 ````````````````````````````````
1516
1517
1518 And indented code can occur immediately before and after other kinds of
1519 blocks:
1520
1521 ```````````````````````````````` example
1522 # Heading
1523     foo
1524 Heading
1525 ------
1526     foo
1527 ----
1528 .
1529 <h1>Heading</h1>
1530 <pre><code>foo
1531 </code></pre>
1532 <h2>Heading</h2>
1533 <pre><code>foo
1534 </code></pre>
1535 <hr />
1536 ````````````````````````````````
1537
1538
1539 The first line can be indented more than four spaces:
1540
1541 ```````````````````````````````` example
1542         foo
1543     bar
1544 .
1545 <pre><code>    foo
1546 bar
1547 </code></pre>
1548 ````````````````````````````````
1549
1550
1551 Blank lines preceding or following an indented code block
1552 are not included in it:
1553
1554 ```````````````````````````````` example
1555
1556     
1557     foo
1558     
1559
1560 .
1561 <pre><code>foo
1562 </code></pre>
1563 ````````````````````````````````
1564
1565
1566 Trailing spaces are included in the code block's content:
1567
1568 ```````````````````````````````` example
1569     foo  
1570 .
1571 <pre><code>foo  
1572 </code></pre>
1573 ````````````````````````````````
1574
1575
1576
1577 ## Fenced code blocks
1578
1579 A [code fence](@) is a sequence
1580 of at least three consecutive backtick characters (`` ` ``) or
1581 tildes (`~`).  (Tildes and backticks cannot be mixed.)
1582 A [fenced code block](@)
1583 begins with a code fence, indented no more than three spaces.
1584
1585 The line with the opening code fence may optionally contain some text
1586 following the code fence; this is trimmed of leading and trailing
1587 spaces and called the [info string](@).
1588 The [info string] may not contain any backtick
1589 characters.  (The reason for this restriction is that otherwise
1590 some inline code would be incorrectly interpreted as the
1591 beginning of a fenced code block.)
1592
1593 The content of the code block consists of all subsequent lines, until
1594 a closing [code fence] of the same type as the code block
1595 began with (backticks or tildes), and with at least as many backticks
1596 or tildes as the opening code fence.  If the leading code fence is
1597 indented N spaces, then up to N spaces of indentation are removed from
1598 each line of the content (if present).  (If a content line is not
1599 indented, it is preserved unchanged.  If it is indented less than N
1600 spaces, all of the indentation is removed.)
1601
1602 The closing code fence may be indented up to three spaces, and may be
1603 followed only by spaces, which are ignored.  If the end of the
1604 containing block (or document) is reached and no closing code fence
1605 has been found, the code block contains all of the lines after the
1606 opening code fence until the end of the containing block (or
1607 document).  (An alternative spec would require backtracking in the
1608 event that a closing code fence is not found.  But this makes parsing
1609 much less efficient, and there seems to be no real down side to the
1610 behavior described here.)
1611
1612 A fenced code block may interrupt a paragraph, and does not require
1613 a blank line either before or after.
1614
1615 The content of a code fence is treated as literal text, not parsed
1616 as inlines.  The first word of the [info string] is typically used to
1617 specify the language of the code sample, and rendered in the `class`
1618 attribute of the `code` tag.  However, this spec does not mandate any
1619 particular treatment of the [info string].
1620
1621 Here is a simple example with backticks:
1622
1623 ```````````````````````````````` example
1624 ```
1625 <
1626  >
1627 ```
1628 .
1629 <pre><code>&lt;
1630  &gt;
1631 </code></pre>
1632 ````````````````````````````````
1633
1634
1635 With tildes:
1636
1637 ```````````````````````````````` example
1638 ~~~
1639 <
1640  >
1641 ~~~
1642 .
1643 <pre><code>&lt;
1644  &gt;
1645 </code></pre>
1646 ````````````````````````````````
1647
1648
1649 The closing code fence must use the same character as the opening
1650 fence:
1651
1652 ```````````````````````````````` example
1653 ```
1654 aaa
1655 ~~~
1656 ```
1657 .
1658 <pre><code>aaa
1659 ~~~
1660 </code></pre>
1661 ````````````````````````````````
1662
1663
1664 ```````````````````````````````` example
1665 ~~~
1666 aaa
1667 ```
1668 ~~~
1669 .
1670 <pre><code>aaa
1671 ```
1672 </code></pre>
1673 ````````````````````````````````
1674
1675
1676 The closing code fence must be at least as long as the opening fence:
1677
1678 ```````````````````````````````` example
1679 ````
1680 aaa
1681 ```
1682 ``````
1683 .
1684 <pre><code>aaa
1685 ```
1686 </code></pre>
1687 ````````````````````````````````
1688
1689
1690 ```````````````````````````````` example
1691 ~~~~
1692 aaa
1693 ~~~
1694 ~~~~
1695 .
1696 <pre><code>aaa
1697 ~~~
1698 </code></pre>
1699 ````````````````````````````````
1700
1701
1702 Unclosed code blocks are closed by the end of the document
1703 (or the enclosing [block quote][block quotes] or [list item][list items]):
1704
1705 ```````````````````````````````` example
1706 ```
1707 .
1708 <pre><code></code></pre>
1709 ````````````````````````````````
1710
1711
1712 ```````````````````````````````` example
1713 `````
1714
1715 ```
1716 aaa
1717 .
1718 <pre><code>
1719 ```
1720 aaa
1721 </code></pre>
1722 ````````````````````````````````
1723
1724
1725 ```````````````````````````````` example
1726 > ```
1727 > aaa
1728
1729 bbb
1730 .
1731 <blockquote>
1732 <pre><code>aaa
1733 </code></pre>
1734 </blockquote>
1735 <p>bbb</p>
1736 ````````````````````````````````
1737
1738
1739 A code block can have all empty lines as its content:
1740
1741 ```````````````````````````````` example
1742 ```
1743
1744   
1745 ```
1746 .
1747 <pre><code>
1748   
1749 </code></pre>
1750 ````````````````````````````````
1751
1752
1753 A code block can be empty:
1754
1755 ```````````````````````````````` example
1756 ```
1757 ```
1758 .
1759 <pre><code></code></pre>
1760 ````````````````````````````````
1761
1762
1763 Fences can be indented.  If the opening fence is indented,
1764 content lines will have equivalent opening indentation removed,
1765 if present:
1766
1767 ```````````````````````````````` example
1768  ```
1769  aaa
1770 aaa
1771 ```
1772 .
1773 <pre><code>aaa
1774 aaa
1775 </code></pre>
1776 ````````````````````````````````
1777
1778
1779 ```````````````````````````````` example
1780   ```
1781 aaa
1782   aaa
1783 aaa
1784   ```
1785 .
1786 <pre><code>aaa
1787 aaa
1788 aaa
1789 </code></pre>
1790 ````````````````````````````````
1791
1792
1793 ```````````````````````````````` example
1794    ```
1795    aaa
1796     aaa
1797   aaa
1798    ```
1799 .
1800 <pre><code>aaa
1801  aaa
1802 aaa
1803 </code></pre>
1804 ````````````````````````````````
1805
1806
1807 Four spaces indentation produces an indented code block:
1808
1809 ```````````````````````````````` example
1810     ```
1811     aaa
1812     ```
1813 .
1814 <pre><code>```
1815 aaa
1816 ```
1817 </code></pre>
1818 ````````````````````````````````
1819
1820
1821 Closing fences may be indented by 0-3 spaces, and their indentation
1822 need not match that of the opening fence:
1823
1824 ```````````````````````````````` example
1825 ```
1826 aaa
1827   ```
1828 .
1829 <pre><code>aaa
1830 </code></pre>
1831 ````````````````````````````````
1832
1833
1834 ```````````````````````````````` example
1835    ```
1836 aaa
1837   ```
1838 .
1839 <pre><code>aaa
1840 </code></pre>
1841 ````````````````````````````````
1842
1843
1844 This is not a closing fence, because it is indented 4 spaces:
1845
1846 ```````````````````````````````` example
1847 ```
1848 aaa
1849     ```
1850 .
1851 <pre><code>aaa
1852     ```
1853 </code></pre>
1854 ````````````````````````````````
1855
1856
1857
1858 Code fences (opening and closing) cannot contain internal spaces:
1859
1860 ```````````````````````````````` example
1861 ``` ```
1862 aaa
1863 .
1864 <p><code></code>
1865 aaa</p>
1866 ````````````````````````````````
1867
1868
1869 ```````````````````````````````` example
1870 ~~~~~~
1871 aaa
1872 ~~~ ~~
1873 .
1874 <pre><code>aaa
1875 ~~~ ~~
1876 </code></pre>
1877 ````````````````````````````````
1878
1879
1880 Fenced code blocks can interrupt paragraphs, and can be followed
1881 directly by paragraphs, without a blank line between:
1882
1883 ```````````````````````````````` example
1884 foo
1885 ```
1886 bar
1887 ```
1888 baz
1889 .
1890 <p>foo</p>
1891 <pre><code>bar
1892 </code></pre>
1893 <p>baz</p>
1894 ````````````````````````````````
1895
1896
1897 Other blocks can also occur before and after fenced code blocks
1898 without an intervening blank line:
1899
1900 ```````````````````````````````` example
1901 foo
1902 ---
1903 ~~~
1904 bar
1905 ~~~
1906 # baz
1907 .
1908 <h2>foo</h2>
1909 <pre><code>bar
1910 </code></pre>
1911 <h1>baz</h1>
1912 ````````````````````````````````
1913
1914
1915 An [info string] can be provided after the opening code fence.
1916 Opening and closing spaces will be stripped, and the first word, prefixed
1917 with `language-`, is used as the value for the `class` attribute of the
1918 `code` element within the enclosing `pre` element.
1919
1920 ```````````````````````````````` example
1921 ```ruby
1922 def foo(x)
1923   return 3
1924 end
1925 ```
1926 .
1927 <pre><code class="language-ruby">def foo(x)
1928   return 3
1929 end
1930 </code></pre>
1931 ````````````````````````````````
1932
1933
1934 ```````````````````````````````` example
1935 ~~~~    ruby startline=3 $%@#$
1936 def foo(x)
1937   return 3
1938 end
1939 ~~~~~~~
1940 .
1941 <pre><code class="language-ruby">def foo(x)
1942   return 3
1943 end
1944 </code></pre>
1945 ````````````````````````````````
1946
1947
1948 ```````````````````````````````` example
1949 ````;
1950 ````
1951 .
1952 <pre><code class="language-;"></code></pre>
1953 ````````````````````````````````
1954
1955
1956 [Info strings] for backtick code blocks cannot contain backticks:
1957
1958 ```````````````````````````````` example
1959 ``` aa ```
1960 foo
1961 .
1962 <p><code>aa</code>
1963 foo</p>
1964 ````````````````````````````````
1965
1966
1967 Closing code fences cannot have [info strings]:
1968
1969 ```````````````````````````````` example
1970 ```
1971 ``` aaa
1972 ```
1973 .
1974 <pre><code>``` aaa
1975 </code></pre>
1976 ````````````````````````````````
1977
1978
1979
1980 ## HTML blocks
1981
1982 An [HTML block](@) is a group of lines that is treated
1983 as raw HTML (and will not be escaped in HTML output).
1984
1985 There are seven kinds of [HTML block], which can be defined
1986 by their start and end conditions.  The block begins with a line that
1987 meets a [start condition](@) (after up to three spaces
1988 optional indentation).  It ends with the first subsequent line that
1989 meets a matching [end condition](@), or the last line of
1990 the document or other [container block]), if no line is encountered that meets the
1991 [end condition].  If the first line meets both the [start condition]
1992 and the [end condition], the block will contain just that line.
1993
1994 1.  **Start condition:**  line begins with the string `<script`,
1995 `<pre`, or `<style` (case-insensitive), followed by whitespace,
1996 the string `>`, or the end of the line.\
1997 **End condition:**  line contains an end tag
1998 `</script>`, `</pre>`, or `</style>` (case-insensitive; it
1999 need not match the start tag).
2000
2001 2.  **Start condition:** line begins with the string `<!--`.\
2002 **End condition:**  line contains the string `-->`.
2003
2004 3.  **Start condition:** line begins with the string `<?`.\
2005 **End condition:** line contains the string `?>`.
2006
2007 4.  **Start condition:** line begins with the string `<!`
2008 followed by an uppercase ASCII letter.\
2009 **End condition:** line contains the character `>`.
2010
2011 5.  **Start condition:**  line begins with the string
2012 `<![CDATA[`.\
2013 **End condition:** line contains the string `]]>`.
2014
2015 6.  **Start condition:** line begins the string `<` or `</`
2016 followed by one of the strings (case-insensitive) `address`,
2017 `article`, `aside`, `base`, `basefont`, `blockquote`, `body`,
2018 `caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`,
2019 `dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`,
2020 `footer`, `form`, `frame`, `frameset`,
2021 `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hr`,
2022 `html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`,
2023 `meta`, `nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`,
2024 `section`, `source`, `summary`, `table`, `tbody`, `td`,
2025 `tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed
2026 by [whitespace], the end of the line, the string `>`, or
2027 the string `/>`.\
2028 **End condition:** line is followed by a [blank line].
2029
2030 7.  **Start condition:**  line begins with a complete [open tag]
2031 or [closing tag] (with any [tag name] other than `script`,
2032 `style`, or `pre`) followed only by [whitespace]
2033 or the end of the line.\
2034 **End condition:** line is followed by a [blank line].
2035
2036 All types of [HTML blocks] except type 7 may interrupt
2037 a paragraph.  Blocks of type 7 may not interrupt a paragraph.
2038 (This restriction is intended to prevent unwanted interpretation
2039 of long tags inside a wrapped paragraph as starting HTML blocks.)
2040
2041 Some simple examples follow.  Here are some basic HTML blocks
2042 of type 6:
2043
2044 ```````````````````````````````` example
2045 <table>
2046   <tr>
2047     <td>
2048            hi
2049     </td>
2050   </tr>
2051 </table>
2052
2053 okay.
2054 .
2055 <table>
2056   <tr>
2057     <td>
2058            hi
2059     </td>
2060   </tr>
2061 </table>
2062 <p>okay.</p>
2063 ````````````````````````````````
2064
2065
2066 ```````````````````````````````` example
2067  <div>
2068   *hello*
2069          <foo><a>
2070 .
2071  <div>
2072   *hello*
2073          <foo><a>
2074 ````````````````````````````````
2075
2076
2077 A block can also start with a closing tag:
2078
2079 ```````````````````````````````` example
2080 </div>
2081 *foo*
2082 .
2083 </div>
2084 *foo*
2085 ````````````````````````````````
2086
2087
2088 Here we have two HTML blocks with a Markdown paragraph between them:
2089
2090 ```````````````````````````````` example
2091 <DIV CLASS="foo">
2092
2093 *Markdown*
2094
2095 </DIV>
2096 .
2097 <DIV CLASS="foo">
2098 <p><em>Markdown</em></p>
2099 </DIV>
2100 ````````````````````````````````
2101
2102
2103 The tag on the first line can be partial, as long
2104 as it is split where there would be whitespace:
2105
2106 ```````````````````````````````` example
2107 <div id="foo"
2108   class="bar">
2109 </div>
2110 .
2111 <div id="foo"
2112   class="bar">
2113 </div>
2114 ````````````````````````````````
2115
2116
2117 ```````````````````````````````` example
2118 <div id="foo" class="bar
2119   baz">
2120 </div>
2121 .
2122 <div id="foo" class="bar
2123   baz">
2124 </div>
2125 ````````````````````````````````
2126
2127
2128 An open tag need not be closed:
2129 ```````````````````````````````` example
2130 <div>
2131 *foo*
2132
2133 *bar*
2134 .
2135 <div>
2136 *foo*
2137 <p><em>bar</em></p>
2138 ````````````````````````````````
2139
2140
2141
2142 A partial tag need not even be completed (garbage
2143 in, garbage out):
2144
2145 ```````````````````````````````` example
2146 <div id="foo"
2147 *hi*
2148 .
2149 <div id="foo"
2150 *hi*
2151 ````````````````````````````````
2152
2153
2154 ```````````````````````````````` example
2155 <div class
2156 foo
2157 .
2158 <div class
2159 foo
2160 ````````````````````````````````
2161
2162
2163 The initial tag doesn't even need to be a valid
2164 tag, as long as it starts like one:
2165
2166 ```````````````````````````````` example
2167 <div *???-&&&-<---
2168 *foo*
2169 .
2170 <div *???-&&&-<---
2171 *foo*
2172 ````````````````````````````````
2173
2174
2175 In type 6 blocks, the initial tag need not be on a line by
2176 itself:
2177
2178 ```````````````````````````````` example
2179 <div><a href="bar">*foo*</a></div>
2180 .
2181 <div><a href="bar">*foo*</a></div>
2182 ````````````````````````````````
2183
2184
2185 ```````````````````````````````` example
2186 <table><tr><td>
2187 foo
2188 </td></tr></table>
2189 .
2190 <table><tr><td>
2191 foo
2192 </td></tr></table>
2193 ````````````````````````````````
2194
2195
2196 Everything until the next blank line or end of document
2197 gets included in the HTML block.  So, in the following
2198 example, what looks like a Markdown code block
2199 is actually part of the HTML block, which continues until a blank
2200 line or the end of the document is reached:
2201
2202 ```````````````````````````````` example
2203 <div></div>
2204 ``` c
2205 int x = 33;
2206 ```
2207 .
2208 <div></div>
2209 ``` c
2210 int x = 33;
2211 ```
2212 ````````````````````````````````
2213
2214
2215 To start an [HTML block] with a tag that is *not* in the
2216 list of block-level tags in (6), you must put the tag by
2217 itself on the first line (and it must be complete):
2218
2219 ```````````````````````````````` example
2220 <a href="foo">
2221 *bar*
2222 </a>
2223 .
2224 <a href="foo">
2225 *bar*
2226 </a>
2227 ````````````````````````````````
2228
2229
2230 In type 7 blocks, the [tag name] can be anything:
2231
2232 ```````````````````````````````` example
2233 <Warning>
2234 *bar*
2235 </Warning>
2236 .
2237 <Warning>
2238 *bar*
2239 </Warning>
2240 ````````````````````````````````
2241
2242
2243 ```````````````````````````````` example
2244 <i class="foo">
2245 *bar*
2246 </i>
2247 .
2248 <i class="foo">
2249 *bar*
2250 </i>
2251 ````````````````````````````````
2252
2253
2254 ```````````````````````````````` example
2255 </ins>
2256 *bar*
2257 .
2258 </ins>
2259 *bar*
2260 ````````````````````````````````
2261
2262
2263 These rules are designed to allow us to work with tags that
2264 can function as either block-level or inline-level tags.
2265 The `<del>` tag is a nice example.  We can surround content with
2266 `<del>` tags in three different ways.  In this case, we get a raw
2267 HTML block, because the `<del>` tag is on a line by itself:
2268
2269 ```````````````````````````````` example
2270 <del>
2271 *foo*
2272 </del>
2273 .
2274 <del>
2275 *foo*
2276 </del>
2277 ````````````````````````````````
2278
2279
2280 In this case, we get a raw HTML block that just includes
2281 the `<del>` tag (because it ends with the following blank
2282 line).  So the contents get interpreted as CommonMark:
2283
2284 ```````````````````````````````` example
2285 <del>
2286
2287 *foo*
2288
2289 </del>
2290 .
2291 <del>
2292 <p><em>foo</em></p>
2293 </del>
2294 ````````````````````````````````
2295
2296
2297 Finally, in this case, the `<del>` tags are interpreted
2298 as [raw HTML] *inside* the CommonMark paragraph.  (Because
2299 the tag is not on a line by itself, we get inline HTML
2300 rather than an [HTML block].)
2301
2302 ```````````````````````````````` example
2303 <del>*foo*</del>
2304 .
2305 <p><del><em>foo</em></del></p>
2306 ````````````````````````````````
2307
2308
2309 HTML tags designed to contain literal content
2310 (`script`, `style`, `pre`), comments, processing instructions,
2311 and declarations are treated somewhat differently.
2312 Instead of ending at the first blank line, these blocks
2313 end at the first line containing a corresponding end tag.
2314 As a result, these blocks can contain blank lines:
2315
2316 A pre tag (type 1):
2317
2318 ```````````````````````````````` example
2319 <pre language="haskell"><code>
2320 import Text.HTML.TagSoup
2321
2322 main :: IO ()
2323 main = print $ parseTags tags
2324 </code></pre>
2325 okay
2326 .
2327 <pre language="haskell"><code>
2328 import Text.HTML.TagSoup
2329
2330 main :: IO ()
2331 main = print $ parseTags tags
2332 </code></pre>
2333 <p>okay</p>
2334 ````````````````````````````````
2335
2336
2337 A script tag (type 1):
2338
2339 ```````````````````````````````` example
2340 <script type="text/javascript">
2341 // JavaScript example
2342
2343 document.getElementById("demo").innerHTML = "Hello JavaScript!";
2344 </script>
2345 okay
2346 .
2347 <script type="text/javascript">
2348 // JavaScript example
2349
2350 document.getElementById("demo").innerHTML = "Hello JavaScript!";
2351 </script>
2352 <p>okay</p>
2353 ````````````````````````````````
2354
2355
2356 A style tag (type 1):
2357
2358 ```````````````````````````````` example
2359 <style
2360   type="text/css">
2361 h1 {color:red;}
2362
2363 p {color:blue;}
2364 </style>
2365 okay
2366 .
2367 <style
2368   type="text/css">
2369 h1 {color:red;}
2370
2371 p {color:blue;}
2372 </style>
2373 <p>okay</p>
2374 ````````````````````````````````
2375
2376
2377 If there is no matching end tag, the block will end at the
2378 end of the document (or the enclosing [block quote][block quotes]
2379 or [list item][list items]):
2380
2381 ```````````````````````````````` example
2382 <style
2383   type="text/css">
2384
2385 foo
2386 .
2387 <style
2388   type="text/css">
2389
2390 foo
2391 ````````````````````````````````
2392
2393
2394 ```````````````````````````````` example
2395 > <div>
2396 > foo
2397
2398 bar
2399 .
2400 <blockquote>
2401 <div>
2402 foo
2403 </blockquote>
2404 <p>bar</p>
2405 ````````````````````````````````
2406
2407
2408 ```````````````````````````````` example
2409 - <div>
2410 - foo
2411 .
2412 <ul>
2413 <li>
2414 <div>
2415 </li>
2416 <li>foo</li>
2417 </ul>
2418 ````````````````````````````````
2419
2420
2421 The end tag can occur on the same line as the start tag:
2422
2423 ```````````````````````````````` example
2424 <style>p{color:red;}</style>
2425 *foo*
2426 .
2427 <style>p{color:red;}</style>
2428 <p><em>foo</em></p>
2429 ````````````````````````````````
2430
2431
2432 ```````````````````````````````` example
2433 <!-- foo -->*bar*
2434 *baz*
2435 .
2436 <!-- foo -->*bar*
2437 <p><em>baz</em></p>
2438 ````````````````````````````````
2439
2440
2441 Note that anything on the last line after the
2442 end tag will be included in the [HTML block]:
2443
2444 ```````````````````````````````` example
2445 <script>
2446 foo
2447 </script>1. *bar*
2448 .
2449 <script>
2450 foo
2451 </script>1. *bar*
2452 ````````````````````````````````
2453
2454
2455 A comment (type 2):
2456
2457 ```````````````````````````````` example
2458 <!-- Foo
2459
2460 bar
2461    baz -->
2462 okay
2463 .
2464 <!-- Foo
2465
2466 bar
2467    baz -->
2468 <p>okay</p>
2469 ````````````````````````````````
2470
2471
2472
2473 A processing instruction (type 3):
2474
2475 ```````````````````````````````` example
2476 <?php
2477
2478   echo '>';
2479
2480 ?>
2481 okay
2482 .
2483 <?php
2484
2485   echo '>';
2486
2487 ?>
2488 <p>okay</p>
2489 ````````````````````````````````
2490
2491
2492 A declaration (type 4):
2493
2494 ```````````````````````````````` example
2495 <!DOCTYPE html>
2496 .
2497 <!DOCTYPE html>
2498 ````````````````````````````````
2499
2500
2501 CDATA (type 5):
2502
2503 ```````````````````````````````` example
2504 <![CDATA[
2505 function matchwo(a,b)
2506 {
2507   if (a < b && a < 0) then {
2508     return 1;
2509
2510   } else {
2511
2512     return 0;
2513   }
2514 }
2515 ]]>
2516 okay
2517 .
2518 <![CDATA[
2519 function matchwo(a,b)
2520 {
2521   if (a < b && a < 0) then {
2522     return 1;
2523
2524   } else {
2525
2526     return 0;
2527   }
2528 }
2529 ]]>
2530 <p>okay</p>
2531 ````````````````````````````````
2532
2533
2534 The opening tag can be indented 1-3 spaces, but not 4:
2535
2536 ```````````````````````````````` example
2537   <!-- foo -->
2538
2539     <!-- foo -->
2540 .
2541   <!-- foo -->
2542 <pre><code>&lt;!-- foo --&gt;
2543 </code></pre>
2544 ````````````````````````````````
2545
2546
2547 ```````````````````````````````` example
2548   <div>
2549
2550     <div>
2551 .
2552   <div>
2553 <pre><code>&lt;div&gt;
2554 </code></pre>
2555 ````````````````````````````````
2556
2557
2558 An HTML block of types 1--6 can interrupt a paragraph, and need not be
2559 preceded by a blank line.
2560
2561 ```````````````````````````````` example
2562 Foo
2563 <div>
2564 bar
2565 </div>
2566 .
2567 <p>Foo</p>
2568 <div>
2569 bar
2570 </div>
2571 ````````````````````````````````
2572
2573
2574 However, a following blank line is needed, except at the end of
2575 a document, and except for blocks of types 1--5, above:
2576
2577 ```````````````````````````````` example
2578 <div>
2579 bar
2580 </div>
2581 *foo*
2582 .
2583 <div>
2584 bar
2585 </div>
2586 *foo*
2587 ````````````````````````````````
2588
2589
2590 HTML blocks of type 7 cannot interrupt a paragraph:
2591
2592 ```````````````````````````````` example
2593 Foo
2594 <a href="bar">
2595 baz
2596 .
2597 <p>Foo
2598 <a href="bar">
2599 baz</p>
2600 ````````````````````````````````
2601
2602
2603 This rule differs from John Gruber's original Markdown syntax
2604 specification, which says:
2605
2606 > The only restrictions are that block-level HTML elements —
2607 > e.g. `<div>`, `<table>`, `<pre>`, `<p>`, etc. — must be separated from
2608 > surrounding content by blank lines, and the start and end tags of the
2609 > block should not be indented with tabs or spaces.
2610
2611 In some ways Gruber's rule is more restrictive than the one given
2612 here:
2613
2614 - It requires that an HTML block be preceded by a blank line.
2615 - It does not allow the start tag to be indented.
2616 - It requires a matching end tag, which it also does not allow to
2617   be indented.
2618
2619 Most Markdown implementations (including some of Gruber's own) do not
2620 respect all of these restrictions.
2621
2622 There is one respect, however, in which Gruber's rule is more liberal
2623 than the one given here, since it allows blank lines to occur inside
2624 an HTML block.  There are two reasons for disallowing them here.
2625 First, it removes the need to parse balanced tags, which is
2626 expensive and can require backtracking from the end of the document
2627 if no matching end tag is found. Second, it provides a very simple
2628 and flexible way of including Markdown content inside HTML tags:
2629 simply separate the Markdown from the HTML using blank lines:
2630
2631 Compare:
2632
2633 ```````````````````````````````` example
2634 <div>
2635
2636 *Emphasized* text.
2637
2638 </div>
2639 .
2640 <div>
2641 <p><em>Emphasized</em> text.</p>
2642 </div>
2643 ````````````````````````````````
2644
2645
2646 ```````````````````````````````` example
2647 <div>
2648 *Emphasized* text.
2649 </div>
2650 .
2651 <div>
2652 *Emphasized* text.
2653 </div>
2654 ````````````````````````````````
2655
2656
2657 Some Markdown implementations have adopted a convention of
2658 interpreting content inside tags as text if the open tag has
2659 the attribute `markdown=1`.  The rule given above seems a simpler and
2660 more elegant way of achieving the same expressive power, which is also
2661 much simpler to parse.
2662
2663 The main potential drawback is that one can no longer paste HTML
2664 blocks into Markdown documents with 100% reliability.  However,
2665 *in most cases* this will work fine, because the blank lines in
2666 HTML are usually followed by HTML block tags.  For example:
2667
2668 ```````````````````````````````` example
2669 <table>
2670
2671 <tr>
2672
2673 <td>
2674 Hi
2675 </td>
2676
2677 </tr>
2678
2679 </table>
2680 .
2681 <table>
2682 <tr>
2683 <td>
2684 Hi
2685 </td>
2686 </tr>
2687 </table>
2688 ````````````````````````````````
2689
2690
2691 There are problems, however, if the inner tags are indented
2692 *and* separated by spaces, as then they will be interpreted as
2693 an indented code block:
2694
2695 ```````````````````````````````` example
2696 <table>
2697
2698   <tr>
2699
2700     <td>
2701       Hi
2702     </td>
2703
2704   </tr>
2705
2706 </table>
2707 .
2708 <table>
2709   <tr>
2710 <pre><code>&lt;td&gt;
2711   Hi
2712 &lt;/td&gt;
2713 </code></pre>
2714   </tr>
2715 </table>
2716 ````````````````````````````````
2717
2718
2719 Fortunately, blank lines are usually not necessary and can be
2720 deleted.  The exception is inside `<pre>` tags, but as described
2721 above, raw HTML blocks starting with `<pre>` *can* contain blank
2722 lines.
2723
2724 ## Link reference definitions
2725
2726 A [link reference definition](@)
2727 consists of a [link label], indented up to three spaces, followed
2728 by a colon (`:`), optional [whitespace] (including up to one
2729 [line ending]), a [link destination],
2730 optional [whitespace] (including up to one
2731 [line ending]), and an optional [link
2732 title], which if it is present must be separated
2733 from the [link destination] by [whitespace].
2734 No further [non-whitespace characters] may occur on the line.
2735
2736 A [link reference definition]
2737 does not correspond to a structural element of a document.  Instead, it
2738 defines a label which can be used in [reference links]
2739 and reference-style [images] elsewhere in the document.  [Link
2740 reference definitions] can come either before or after the links that use
2741 them.
2742
2743 ```````````````````````````````` example
2744 [foo]: /url "title"
2745
2746 [foo]
2747 .
2748 <p><a href="/url" title="title">foo</a></p>
2749 ````````````````````````````````
2750
2751
2752 ```````````````````````````````` example
2753    [foo]: 
2754       /url  
2755            'the title'  
2756
2757 [foo]
2758 .
2759 <p><a href="/url" title="the title">foo</a></p>
2760 ````````````````````````````````
2761
2762
2763 ```````````````````````````````` example
2764 [Foo*bar\]]:my_(url) 'title (with parens)'
2765
2766 [Foo*bar\]]
2767 .
2768 <p><a href="my_(url)" title="title (with parens)">Foo*bar]</a></p>
2769 ````````````````````````````````
2770
2771
2772 ```````````````````````````````` example
2773 [Foo bar]:
2774 <my%20url>
2775 'title'
2776
2777 [Foo bar]
2778 .
2779 <p><a href="my%20url" title="title">Foo bar</a></p>
2780 ````````````````````````````````
2781
2782
2783 The title may extend over multiple lines:
2784
2785 ```````````````````````````````` example
2786 [foo]: /url '
2787 title
2788 line1
2789 line2
2790 '
2791
2792 [foo]
2793 .
2794 <p><a href="/url" title="
2795 title
2796 line1
2797 line2
2798 ">foo</a></p>
2799 ````````````````````````````````
2800
2801
2802 However, it may not contain a [blank line]:
2803
2804 ```````````````````````````````` example
2805 [foo]: /url 'title
2806
2807 with blank line'
2808
2809 [foo]
2810 .
2811 <p>[foo]: /url 'title</p>
2812 <p>with blank line'</p>
2813 <p>[foo]</p>
2814 ````````````````````````````````
2815
2816
2817 The title may be omitted:
2818
2819 ```````````````````````````````` example
2820 [foo]:
2821 /url
2822
2823 [foo]
2824 .
2825 <p><a href="/url">foo</a></p>
2826 ````````````````````````````````
2827
2828
2829 The link destination may not be omitted:
2830
2831 ```````````````````````````````` example
2832 [foo]:
2833
2834 [foo]
2835 .
2836 <p>[foo]:</p>
2837 <p>[foo]</p>
2838 ````````````````````````````````
2839
2840
2841 Both title and destination can contain backslash escapes
2842 and literal backslashes:
2843
2844 ```````````````````````````````` example
2845 [foo]: /url\bar\*baz "foo\"bar\baz"
2846
2847 [foo]
2848 .
2849 <p><a href="/url%5Cbar*baz" title="foo&quot;bar\baz">foo</a></p>
2850 ````````````````````````````````
2851
2852
2853 A link can come before its corresponding definition:
2854
2855 ```````````````````````````````` example
2856 [foo]
2857
2858 [foo]: url
2859 .
2860 <p><a href="url">foo</a></p>
2861 ````````````````````````````````
2862
2863
2864 If there are several matching definitions, the first one takes
2865 precedence:
2866
2867 ```````````````````````````````` example
2868 [foo]
2869
2870 [foo]: first
2871 [foo]: second
2872 .
2873 <p><a href="first">foo</a></p>
2874 ````````````````````````````````
2875
2876
2877 As noted in the section on [Links], matching of labels is
2878 case-insensitive (see [matches]).
2879
2880 ```````````````````````````````` example
2881 [FOO]: /url
2882
2883 [Foo]
2884 .
2885 <p><a href="/url">Foo</a></p>
2886 ````````````````````````````````
2887
2888
2889 ```````````````````````````````` example
2890 [ΑΓΩ]: /φου
2891
2892 [αγω]
2893 .
2894 <p><a href="/%CF%86%CE%BF%CF%85">αγω</a></p>
2895 ````````````````````````````````
2896
2897
2898 Here is a link reference definition with no corresponding link.
2899 It contributes nothing to the document.
2900
2901 ```````````````````````````````` example
2902 [foo]: /url
2903 .
2904 ````````````````````````````````
2905
2906
2907 Here is another one:
2908
2909 ```````````````````````````````` example
2910 [
2911 foo
2912 ]: /url
2913 bar
2914 .
2915 <p>bar</p>
2916 ````````````````````````````````
2917
2918
2919 This is not a link reference definition, because there are
2920 [non-whitespace characters] after the title:
2921
2922 ```````````````````````````````` example
2923 [foo]: /url "title" ok
2924 .
2925 <p>[foo]: /url &quot;title&quot; ok</p>
2926 ````````````````````````````````
2927
2928
2929 This is a link reference definition, but it has no title:
2930
2931 ```````````````````````````````` example
2932 [foo]: /url
2933 "title" ok
2934 .
2935 <p>&quot;title&quot; ok</p>
2936 ````````````````````````````````
2937
2938
2939 This is not a link reference definition, because it is indented
2940 four spaces:
2941
2942 ```````````````````````````````` example
2943     [foo]: /url "title"
2944
2945 [foo]
2946 .
2947 <pre><code>[foo]: /url &quot;title&quot;
2948 </code></pre>
2949 <p>[foo]</p>
2950 ````````````````````````````````
2951
2952
2953 This is not a link reference definition, because it occurs inside
2954 a code block:
2955
2956 ```````````````````````````````` example
2957 ```
2958 [foo]: /url
2959 ```
2960
2961 [foo]
2962 .
2963 <pre><code>[foo]: /url
2964 </code></pre>
2965 <p>[foo]</p>
2966 ````````````````````````````````
2967
2968
2969 A [link reference definition] cannot interrupt a paragraph.
2970
2971 ```````````````````````````````` example
2972 Foo
2973 [bar]: /baz
2974
2975 [bar]
2976 .
2977 <p>Foo
2978 [bar]: /baz</p>
2979 <p>[bar]</p>
2980 ````````````````````````````````
2981
2982
2983 However, it can directly follow other block elements, such as headings
2984 and thematic breaks, and it need not be followed by a blank line.
2985
2986 ```````````````````````````````` example
2987 # [Foo]
2988 [foo]: /url
2989 > bar
2990 .
2991 <h1><a href="/url">Foo</a></h1>
2992 <blockquote>
2993 <p>bar</p>
2994 </blockquote>
2995 ````````````````````````````````
2996
2997
2998 Several [link reference definitions]
2999 can occur one after another, without intervening blank lines.
3000
3001 ```````````````````````````````` example
3002 [foo]: /foo-url "foo"
3003 [bar]: /bar-url
3004   "bar"
3005 [baz]: /baz-url
3006
3007 [foo],
3008 [bar],
3009 [baz]
3010 .
3011 <p><a href="/foo-url" title="foo">foo</a>,
3012 <a href="/bar-url" title="bar">bar</a>,
3013 <a href="/baz-url">baz</a></p>
3014 ````````````````````````````````
3015
3016
3017 [Link reference definitions] can occur
3018 inside block containers, like lists and block quotations.  They
3019 affect the entire document, not just the container in which they
3020 are defined:
3021
3022 ```````````````````````````````` example
3023 [foo]
3024
3025 > [foo]: /url
3026 .
3027 <p><a href="/url">foo</a></p>
3028 <blockquote>
3029 </blockquote>
3030 ````````````````````````````````
3031
3032
3033
3034 ## Paragraphs
3035
3036 A sequence of non-blank lines that cannot be interpreted as other
3037 kinds of blocks forms a [paragraph](@).
3038 The contents of the paragraph are the result of parsing the
3039 paragraph's raw content as inlines.  The paragraph's raw content
3040 is formed by concatenating the lines and removing initial and final
3041 [whitespace].
3042
3043 A simple example with two paragraphs:
3044
3045 ```````````````````````````````` example
3046 aaa
3047
3048 bbb
3049 .
3050 <p>aaa</p>
3051 <p>bbb</p>
3052 ````````````````````````````````
3053
3054
3055 Paragraphs can contain multiple lines, but no blank lines:
3056
3057 ```````````````````````````````` example
3058 aaa
3059 bbb
3060
3061 ccc
3062 ddd
3063 .
3064 <p>aaa
3065 bbb</p>
3066 <p>ccc
3067 ddd</p>
3068 ````````````````````````````````
3069
3070
3071 Multiple blank lines between paragraph have no effect:
3072
3073 ```````````````````````````````` example
3074 aaa
3075
3076
3077 bbb
3078 .
3079 <p>aaa</p>
3080 <p>bbb</p>
3081 ````````````````````````````````
3082
3083
3084 Leading spaces are skipped:
3085
3086 ```````````````````````````````` example
3087   aaa
3088  bbb
3089 .
3090 <p>aaa
3091 bbb</p>
3092 ````````````````````````````````
3093
3094
3095 Lines after the first may be indented any amount, since indented
3096 code blocks cannot interrupt paragraphs.
3097
3098 ```````````````````````````````` example
3099 aaa
3100              bbb
3101                                        ccc
3102 .
3103 <p>aaa
3104 bbb
3105 ccc</p>
3106 ````````````````````````````````
3107
3108
3109 However, the first line may be indented at most three spaces,
3110 or an indented code block will be triggered:
3111
3112 ```````````````````````````````` example
3113    aaa
3114 bbb
3115 .
3116 <p>aaa
3117 bbb</p>
3118 ````````````````````````````````
3119
3120
3121 ```````````````````````````````` example
3122     aaa
3123 bbb
3124 .
3125 <pre><code>aaa
3126 </code></pre>
3127 <p>bbb</p>
3128 ````````````````````````````````
3129
3130
3131 Final spaces are stripped before inline parsing, so a paragraph
3132 that ends with two or more spaces will not end with a [hard line
3133 break]:
3134
3135 ```````````````````````````````` example
3136 aaa     
3137 bbb     
3138 .
3139 <p>aaa<br />
3140 bbb</p>
3141 ````````````````````````````````
3142
3143
3144 ## Blank lines
3145
3146 [Blank lines] between block-level elements are ignored,