clover's git

markodown

1	---
2	title: CommonMark Spec
3	author: John MacFarlane
4	version: 0.30
5	date: '2021-06-19'
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	Note that not every feature of the HTML samples is mandated by
274	the spec. For example, the spec says what counts as a link
275	destination, but it doesn't mandate that non-ASCII characters in
276	the URL be percent-encoded. To use the automatic tests,
277	implementers will need to provide a renderer that conforms to
278	the expectations of the spec examples (percent-encoding
279	non-ASCII characters in URLs). But a conforming implementation
280	can use a different renderer and may choose not to
281	percent-encode non-ASCII characters in URLs.
282
283	This document is generated from a text file, `spec.txt`, written
284	in Markdown with a small extension for the side-by-side tests.
285	The script `tools/makespec.py` can be used to convert `spec.txt` into
286	HTML or CommonMark (which can then be converted into other formats).
287
288	In the examples, the `→` character is used to represent tabs.
289
290	# Preliminaries
291
292	## Characters and lines
293
294	Any sequence of [characters] is a valid CommonMark
295	document.
296
297	A [character](@) is a Unicode code point. Although some
298	code points (for example, combining accents) do not correspond to
299	characters in an intuitive sense, all code points count as characters
300	for purposes of this spec.
301
302	This spec does not specify an encoding; it thinks of lines as composed
303	of [characters] rather than bytes. A conforming parser may be limited
304	to a certain encoding.
305
306	A [line](@) is a sequence of zero or more [characters]
307	other than line feed (`U+000A`) or carriage return (`U+000D`),
308	followed by a [line ending] or by the end of file.
309
310	A [line ending](@) is a line feed (`U+000A`), a carriage return
311	(`U+000D`) not followed by a line feed, or a carriage return and a
312	following line feed.
313
314	A line containing no characters, or a line containing only spaces
315	(`U+0020`) or tabs (`U+0009`), is called a [blank line](@).
316
317	The following definitions of character classes will be used in this spec:
318
319	A [Unicode whitespace character](@) is
320	any code point in the Unicode `Zs` general category, or a tab (`U+0009`),
321	line feed (`U+000A`), form feed (`U+000C`), or carriage return (`U+000D`).
322
323	[Unicode whitespace](@) is a sequence of one or more
324	[Unicode whitespace characters].
325
326	A [tab](@) is `U+0009`.
327
328	A [space](@) is `U+0020`.
329
330	An [ASCII control character](@) is a character between `U+0000–1F` (both
331	including) or `U+007F`.
332
333	An [ASCII punctuation character](@)
334	is `!`, `"`, `#`, `$`, `%`, `&`, `'`, `(`, `)`,
335	`*`, `+`, `,`, `-`, `.`, `/` (U+0021–2F),
336	`:`, `;`, `<`, `=`, `>`, `?`, `@` (U+003A–0040),
337	`[`, `\`, `]`, `^`, `_`, `` ` `` (U+005B–0060),
338	`{`, `|`, `}`, or `~` (U+007B–007E).
339
340	A [Unicode punctuation character](@) is an [ASCII
341	punctuation character] or anything in
342	the general Unicode categories `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`.
343
344	## Tabs
345
346	Tabs in lines are not expanded to [spaces]. However,
347	in contexts where spaces help to define block structure,
348	tabs behave as if they were replaced by spaces with a tab stop
349	of 4 characters.
350
351	Thus, for example, a tab can be used instead of four spaces
352	in an indented code block. (Note, however, that internal
353	tabs are passed through as literal tabs, not expanded to
354	spaces.)
355
356	```````````````````````````````` example
357	→foo→baz→→bim
358	.
359	<pre><code>foo→baz→→bim
360	</code></pre>
361	````````````````````````````````
362
363	```````````````````````````````` example
364	→foo→baz→→bim
365	.
366	<pre><code>foo→baz→→bim
367	</code></pre>
368	````````````````````````````````
369
370	```````````````````````````````` example
371	a→a
372	ὐ→a
373	.
374	<pre><code>a→a
375	ὐ→a
376	</code></pre>
377	````````````````````````````````
378
379	In the following example, a continuation paragraph of a list
380	item is indented with a tab; this has exactly the same effect
381	as indentation with four spaces would:
382
383	```````````````````````````````` example
384	- foo
385
386	→bar
387	.
388	<ul>
389	<li>
390	<p>foo</p>
391	<p>bar</p>
392	</li>
393	</ul>
394	````````````````````````````````
395
396	```````````````````````````````` example
397	- foo
398
399	→→bar
400	.
401	<ul>
402	<li>
403	<p>foo</p>
404	<pre><code> bar
405	</code></pre>
406	</li>
407	</ul>
408	````````````````````````````````
409
410	Normally the `>` that begins a block quote may be followed
411	optionally by a space, which is not considered part of the
412	content. In the following case `>` is followed by a tab,
413	which is treated as if it were expanded into three spaces.
414	Since one of these spaces is considered part of the
415	delimiter, `foo` is considered to be indented six spaces
416	inside the block quote context, so we get an indented
417	code block starting with two spaces.
418
419	```````````````````````````````` example
420	>→→foo
421	.
422	<blockquote>
423	<pre><code> foo
424	</code></pre>
425	</blockquote>
426	````````````````````````````````
427
428	```````````````````````````````` example
429	-→→foo
430	.
431	<ul>
432	<li>
433	<pre><code> foo
434	</code></pre>
435	</li>
436	</ul>
437	````````````````````````````````
438
439
440	```````````````````````````````` example
441	foo
442	→bar
443	.
444	<pre><code>foo
445	bar
446	</code></pre>
447	````````````````````````````````
448
449	```````````````````````````````` example
450	- foo
451	- bar
452	→ - baz
453	.
454	<ul>
455	<li>foo
456	<ul>
457	<li>bar
458	<ul>
459	<li>baz</li>
460	</ul>
461	</li>
462	</ul>
463	</li>
464	</ul>
465	````````````````````````````````
466
467	```````````````````````````````` example
468	#→Foo
469	.
470	<h1>Foo</h1>
471	````````````````````````````````
472
473	```````````````````````````````` example
474	*→*→*→
475	.
476	<hr />
477	````````````````````````````````
478
479
480	## Insecure characters
481
482	For security reasons, the Unicode character `U+0000` must be replaced
483	with the REPLACEMENT CHARACTER (`U+FFFD`).
484
485
486	## Backslash escapes
487
488	Any ASCII punctuation character may be backslash-escaped:
489
490	```````````````````````````````` example
491	\!\"\#\$\%\&\'\(\)\*\+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}\~
492	.
493	<p>!&quot;#$%&amp;'()*+,-./:;&lt;=&gt;?@[\]^_`{|}~</p>
494	````````````````````````````````
495
496
497	Backslashes before other characters are treated as literal
498	backslashes:
499
500	```````````````````````````````` example
501	\→\A\a\ \3\φ\«
502	.
503	<p>\→\A\a\ \3\φ\«</p>
504	````````````````````````````````
505
506
507	Escaped characters are treated as regular characters and do
508	not have their usual Markdown meanings:
509
510	```````````````````````````````` example
511	\*not emphasized*
512	\<br/> not a tag
513	\[not a link](/foo)
514	\`not code`
515	1\. not a list
516	\* not a list
517	\# not a heading
518	\[foo]: /url "not a reference"
519	\&ouml; not a character entity
520	.
521	<p>*not emphasized*
522	&lt;br/&gt; not a tag
523	[not a link](/foo)
524	`not code`
525	1. not a list
526	* not a list
527	# not a heading
528	[foo]: /url &quot;not a reference&quot;
529	&amp;ouml; not a character entity</p>
530	````````````````````````````````
531
532
533	If a backslash is itself escaped, the following character is not:
534
535	```````````````````````````````` example
536	\\*emphasis*
537	.
538	<p>\<em>emphasis</em></p>
539	````````````````````````````````
540
541
542	A backslash at the end of the line is a [hard line break]:
543
544	```````````````````````````````` example
545	foo\
546	bar
547	.
548	<p>foo<br />
549	bar</p>
550	````````````````````````````````
551
552
553	Backslash escapes do not work in code blocks, code spans, autolinks, or
554	raw HTML:
555
556	```````````````````````````````` example
557	`` \[\` ``
558	.
559	<p><code>\[\`</code></p>
560	````````````````````````````````
561
562
563	```````````````````````````````` example
564	\[\]
565	.
566	<pre><code>\[\]
567	</code></pre>
568	````````````````````````````````
569
570
571	```````````````````````````````` example
572	~~~
573	\[\]
574	~~~
575	.
576	<pre><code>\[\]
577	</code></pre>
578	````````````````````````````````
579
580
581	```````````````````````````````` example
582	<http://example.com?find=\*>
583	.
584	<p><a href="http://example.com?find=%5C*">http://example.com?find=\*</a></p>
585	````````````````````````````````
586
587
588	```````````````````````````````` example
589	<a href="/bar\/)">
590	.
591	<a href="/bar\/)">
592	````````````````````````````````
593
594
595	But they work in all other contexts, including URLs and link titles,
596	link references, and [info strings] in [fenced code blocks]:
597
598	```````````````````````````````` example
599	[foo](/bar\* "ti\*tle")
600	.
601	<p><a href="/bar*" title="ti*tle">foo</a></p>
602	````````````````````````````````
603
604
605	```````````````````````````````` example
606	[foo]
607
608	[foo]: /bar\* "ti\*tle"
609	.
610	<p><a href="/bar*" title="ti*tle">foo</a></p>
611	````````````````````````````````
612
613
614	```````````````````````````````` example
615	``` foo\+bar
616	foo
617	```
618	.
619	<pre><code class="language-foo+bar">foo
620	</code></pre>
621	````````````````````````````````
622
623
624	## Entity and numeric character references
625
626	Valid HTML entity references and numeric character references
627	can be used in place of the corresponding Unicode character,
628	with the following exceptions:
629
630	- Entity and character references are not recognized in code
631	blocks and code spans.
632
633	- Entity and character references cannot stand in place of
634	special characters that define structural elements in
635	CommonMark. For example, although `&#42;` can be used
636	in place of a literal `*` character, `&#42;` cannot replace
637	`*` in emphasis delimiters, bullet list markers, or thematic
638	breaks.
639
640	Conforming CommonMark parsers need not store information about
641	whether a particular character was represented in the source
642	using a Unicode character or an entity reference.
643
644	[Entity references](@) consist of `&` + any of the valid
645	HTML5 entity names + `;`. The
646	document <https://html.spec.whatwg.org/entities.json>
647	is used as an authoritative source for the valid entity
648	references and their corresponding code points.
649
650	```````````````````````````````` example
651	&nbsp; &amp; &copy; &AElig; &Dcaron;
652	&frac34; &HilbertSpace; &DifferentialD;
653	&ClockwiseContourIntegral; &ngE;
654	.
655	<p>  &amp; © Æ Ď
656	¾ ℋ ⅆ
657	∲ ≧̸</p>
658	````````````````````````````````
659
660
661	[Decimal numeric character
662	references](@)
663	consist of `&#` + a string of 1--7 arabic digits + `;`. A
664	numeric character reference is parsed as the corresponding
665	Unicode character. Invalid Unicode code points will be replaced by
666	the REPLACEMENT CHARACTER (`U+FFFD`). For security reasons,
667	the code point `U+0000` will also be replaced by `U+FFFD`.
668
669	```````````````````````````````` example
670	&#35; &#1234; &#992; &#0;
671	.
672	<p># Ӓ Ϡ �</p>
673	````````````````````````````````
674
675
676	[Hexadecimal numeric character
677	references](@) consist of `&#` +
678	either `X` or `x` + a string of 1-6 hexadecimal digits + `;`.
679	They too are parsed as the corresponding Unicode character (this
680	time specified with a hexadecimal numeral instead of decimal).
681
682	```````````````````````````````` example
683	&#X22; &#XD06; &#xcab;
684	.
685	<p>&quot; ആ ಫ</p>
686	````````````````````````````````
687
688
689	Here are some nonentities:
690
691	```````````````````````````````` example
692	&nbsp &x; &#; &#x;
693	&#87654321;
694	&#abcdef0;
695	&ThisIsNotDefined; &hi?;
696	.
697	<p>&amp;nbsp &amp;x; &amp;#; &amp;#x;
698	&amp;#87654321;
699	&amp;#abcdef0;
700	&amp;ThisIsNotDefined; &amp;hi?;</p>
701	````````````````````````````````
702
703
704	Although HTML5 does accept some entity references
705	without a trailing semicolon (such as `&copy`), these are not
706	recognized here, because it makes the grammar too ambiguous:
707
708	```````````````````````````````` example
709	&copy
710	.
711	<p>&amp;copy</p>
712	````````````````````````````````
713
714
715	Strings that are not on the list of HTML5 named entities are not
716	recognized as entity references either:
717
718	```````````````````````````````` example
719	&MadeUpEntity;
720	.
721	<p>&amp;MadeUpEntity;</p>
722	````````````````````````````````
723
724
725	Entity and numeric character references are recognized in any
726	context besides code spans or code blocks, including
727	URLs, [link titles], and [fenced code block][] [info strings]:
728
729	```````````````````````````````` example
730	<a href="&ouml;&ouml;.html">
731	.
732	<a href="&ouml;&ouml;.html">
733	````````````````````````````````
734
735
736	```````````````````````````````` example
737	[foo](/f&ouml;&ouml; "f&ouml;&ouml;")
738	.
739	<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
740	````````````````````````````````
741
742
743	```````````````````````````````` example
744	[foo]
745
746	[foo]: /f&ouml;&ouml; "f&ouml;&ouml;"
747	.
748	<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
749	````````````````````````````````
750
751
752	```````````````````````````````` example
753	``` f&ouml;&ouml;
754	foo
755	```
756	.
757	<pre><code class="language-föö">foo
758	</code></pre>
759	````````````````````````````````
760
761
762	Entity and numeric character references are treated as literal
763	text in code spans and code blocks:
764
765	```````````````````````````````` example
766	`f&ouml;&ouml;`
767	.
768	<p><code>f&amp;ouml;&amp;ouml;</code></p>
769	````````````````````````````````
770
771
772	```````````````````````````````` example
773	f&ouml;f&ouml;
774	.
775	<pre><code>f&amp;ouml;f&amp;ouml;
776	</code></pre>
777	````````````````````````````````
778
779
780	Entity and numeric character references cannot be used
781	in place of symbols indicating structure in CommonMark
782	documents.
783
784	```````````````````````````````` example
785	&#42;foo&#42;
786	*foo*
787	.
788	<p>*foo*
789	<em>foo</em></p>
790	````````````````````````````````
791
792	```````````````````````````````` example
793	&#42; foo
794
795	* foo
796	.
797	<p>* foo</p>
798	<ul>
799	<li>foo</li>
800	</ul>
801	````````````````````````````````
802
803	```````````````````````````````` example
804	foo&#10;&#10;bar
805	.
806	<p>foo
807
808	bar</p>
809	````````````````````````````````
810
811	```````````````````````````````` example
812	&#9;foo
813	.
814	<p>→foo</p>
815	````````````````````````````````
816
817
818	```````````````````````````````` example
819	[a](url &quot;tit&quot;)
820	.
821	<p>[a](url &quot;tit&quot;)</p>
822	````````````````````````````````
823
824
825
826	# Blocks and inlines
827
828	We can think of a document as a sequence of
829	[blocks](@)---structural elements like paragraphs, block
830	quotations, lists, headings, rules, and code blocks. Some blocks (like
831	block quotes and list items) contain other blocks; others (like
832	headings and paragraphs) contain [inline](@) content---text,
833	links, emphasized text, images, code spans, and so on.
834
835	## Precedence
836
837	Indicators of block structure always take precedence over indicators
838	of inline structure. So, for example, the following is a list with
839	two items, not a list with one item containing a code span:
840
841	```````````````````````````````` example
842	- `one
843	- two`
844	.
845	<ul>
846	<li>`one</li>
847	<li>two`</li>
848	</ul>
849	````````````````````````````````
850
851
852	This means that parsing can proceed in two steps: first, the block
853	structure of the document can be discerned; second, text lines inside
854	paragraphs, headings, and other block constructs can be parsed for inline
855	structure. The second step requires information about link reference
856	definitions that will be available only at the end of the first
857	step. Note that the first step requires processing lines in sequence,
858	but the second can be parallelized, since the inline parsing of
859	one block element does not affect the inline parsing of any other.
860
861	## Container blocks and leaf blocks
862
863	We can divide blocks into two types:
864	[container blocks](#container-blocks),
865	which can contain other blocks, and [leaf blocks](#leaf-blocks),
866	which cannot.
867
868	# Leaf blocks
869
870	This section describes the different kinds of leaf block that make up a
871	Markdown document.
872
873	## Thematic breaks
874
875	A line consisting of optionally up to three spaces of indentation, followed by a
876	sequence of three or more matching `-`, `_`, or `*` characters, each followed
877	optionally by any number of spaces or tabs, forms a
878	[thematic break](@).
879
880	```````````````````````````````` example
881	***
882	---
883	___
884	.
885	<hr />
886	<hr />
887	<hr />
888	````````````````````````````````
889
890
891	Wrong characters:
892
893	```````````````````````````````` example
894	+++
895	.
896	<p>+++</p>
897	````````````````````````````````
898
899
900	```````````````````````````````` example
901	===
902	.
903	<p>===</p>
904	````````````````````````````````
905
906
907	Not enough characters:
908
909	```````````````````````````````` example
910	--
911	**
912	__
913	.
914	<p>--
915	**
916	__</p>
917	````````````````````````````````
918
919
920	Up to three spaces of indentation are allowed:
921
922	```````````````````````````````` example
923	***
924	***
925	***
926	.
927	<hr />
928	<hr />
929	<hr />
930	````````````````````````````````
931
932
933	Four spaces of indentation is too many:
934
935	```````````````````````````````` example
936	***
937	.
938	<pre><code>***
939	</code></pre>
940	````````````````````````````````
941
942
943	```````````````````````````````` example
944	Foo
945	***
946	.
947	<p>Foo
948	***</p>
949	````````````````````````````````
950
951
952	More than three characters may be used:
953
954	```````````````````````````````` example
955	_____________________________________
956	.
957	<hr />
958	````````````````````````````````
959
960
961	Spaces and tabs are allowed between the characters:
962
963	```````````````````````````````` example
964	- - -
965	.
966	<hr />
967	````````````````````````````````
968
969
970	```````````````````````````````` example
971	** * ** * ** * **
972	.
973	<hr />
974	````````````````````````````````
975
976
977	```````````````````````````````` example
978	- - - -
979	.
980	<hr />
981	````````````````````````````````
982
983
984	Spaces and tabs are allowed at the end:
985
986	```````````````````````````````` example
987	- - - -
988	.
989	<hr />
990	````````````````````````````````
991
992
993	However, no other characters may occur in the line:
994
995	```````````````````````````````` example
996	_ _ _ _ a
997
998	a------
999
1000	---a---
1001	.
1002	<p>_ _ _ _ a</p>
1003	<p>a------</p>
1004	<p>---a---</p>
1005	````````````````````````````````
1006
1007
1008	It is required that all of the characters other than spaces or tabs be the same.
1009	So, this is not a thematic break:
1010
1011	```````````````````````````````` example
1012	*-*
1013	.
1014	<p><em>-</em></p>
1015	````````````````````````````````
1016
1017
1018	Thematic breaks do not need blank lines before or after:
1019
1020	```````````````````````````````` example
1021	- foo
1022	***
1023	- bar
1024	.
1025	<ul>
1026	<li>foo</li>
1027	</ul>
1028	<hr />
1029	<ul>
1030	<li>bar</li>
1031	</ul>
1032	````````````````````````````````
1033
1034
1035	Thematic breaks can interrupt a paragraph:
1036
1037	```````````````````````````````` example
1038	Foo
1039	***
1040	bar
1041	.
1042	<p>Foo</p>
1043	<hr />
1044	<p>bar</p>
1045	````````````````````````````````
1046
1047
1048	If a line of dashes that meets the above conditions for being a
1049	thematic break could also be interpreted as the underline of a [setext
1050	heading], the interpretation as a
1051	[setext heading] takes precedence. Thus, for example,
1052	this is a setext heading, not a paragraph followed by a thematic break:
1053
1054	```````````````````````````````` example
1055	Foo
1056	---
1057	bar
1058	.
1059	<h2>Foo</h2>
1060	<p>bar</p>
1061	````````````````````````````````
1062
1063
1064	When both a thematic break and a list item are possible
1065	interpretations of a line, the thematic break takes precedence:
1066
1067	```````````````````````````````` example
1068	* Foo
1069	* * *
1070	* Bar
1071	.
1072	<ul>
1073	<li>Foo</li>
1074	</ul>
1075	<hr />
1076	<ul>
1077	<li>Bar</li>
1078	</ul>
1079	````````````````````````````````
1080
1081
1082	If you want a thematic break in a list item, use a different bullet:
1083
1084	```````````````````````````````` example
1085	- Foo
1086	- * * *
1087	.
1088	<ul>
1089	<li>Foo</li>
1090	<li>
1091	<hr />
1092	</li>
1093	</ul>
1094	````````````````````````````````
1095
1096
1097	## ATX headings
1098
1099	An [ATX heading](@)
1100	consists of a string of characters, parsed as inline content, between an
1101	opening sequence of 1--6 unescaped `#` characters and an optional
1102	closing sequence of any number of unescaped `#` characters.
1103	The opening sequence of `#` characters must be followed by spaces or tabs, or
1104	by the end of line. The optional closing sequence of `#`s must be preceded by
1105	spaces or tabs and may be followed by spaces or tabs only. The opening
1106	`#` character may be preceded by up to three spaces of indentation. The raw
1107	contents of the heading are stripped of leading and trailing space or tabs
1108	before being parsed as inline content. The heading level is equal to the number
1109	of `#` characters in the opening sequence.
1110
1111	Simple headings:
1112
1113	```````````````````````````````` example
1114	# foo
1115	## foo
1116	### foo
1117	#### foo
1118	##### foo
1119	###### foo
1120	.
1121	<h1>foo</h1>
1122	<h2>foo</h2>
1123	<h3>foo</h3>
1124	<h4>foo</h4>
1125	<h5>foo</h5>
1126	<h6>foo</h6>
1127	````````````````````````````````
1128
1129
1130	More than six `#` characters is not a heading:
1131
1132	```````````````````````````````` example
1133	####### foo
1134	.
1135	<p>####### foo</p>
1136	````````````````````````````````
1137
1138
1139	At least one space or tab is required between the `#` characters and the
1140	heading's contents, unless the heading is empty. Note that many
1141	implementations currently do not require the space. However, the
1142	space was required by the
1143	[original ATX implementation](http://www.aaronsw.com/2002/atx/atx.py),
1144	and it helps prevent things like the following from being parsed as
1145	headings:
1146
1147	```````````````````````````````` example
1148	#5 bolt
1149
1150	#hashtag
1151	.
1152	<p>#5 bolt</p>
1153	<p>#hashtag</p>
1154	````````````````````````````````
1155
1156
1157	This is not a heading, because the first `#` is escaped:
1158
1159	```````````````````````````````` example
1160	\## foo
1161	.
1162	<p>## foo</p>
1163	````````````````````````````````
1164
1165
1166	Contents are parsed as inlines:
1167
1168	```````````````````````````````` example
1169	# foo *bar* \*baz\*
1170	.
1171	<h1>foo <em>bar</em> *baz*</h1>
1172	````````````````````````````````
1173
1174
1175	Leading and trailing spaces or tabs are ignored in parsing inline content:
1176
1177	```````````````````````````````` example
1178	# foo
1179	.
1180	<h1>foo</h1>
1181	````````````````````````````````
1182
1183
1184	Up to three spaces of indentation are allowed:
1185
1186	```````````````````````````````` example
1187	### foo
1188	## foo
1189	# foo
1190	.
1191	<h3>foo</h3>
1192	<h2>foo</h2>
1193	<h1>foo</h1>
1194	````````````````````````````````
1195
1196
1197	Four spaces of indentation is too many:
1198
1199	```````````````````````````````` example
1200	# foo
1201	.
1202	<pre><code># foo
1203	</code></pre>
1204	````````````````````````````````
1205
1206
1207	```````````````````````````````` example
1208	foo
1209	# bar
1210	.
1211	<p>foo
1212	# bar</p>
1213	````````````````````````````````
1214
1215
1216	A closing sequence of `#` characters is optional:
1217
1218	```````````````````````````````` example
1219	## foo ##
1220	### bar ###
1221	.
1222	<h2>foo</h2>
1223	<h3>bar</h3>
1224	````````````````````````````````
1225
1226
1227	It need not be the same length as the opening sequence:
1228
1229	```````````````````````````````` example
1230	# foo ##################################
1231	##### foo ##
1232	.
1233	<h1>foo</h1>
1234	<h5>foo</h5>
1235	````````````````````````````````
1236
1237
1238	Spaces or tabs are allowed after the closing sequence:
1239
1240	```````````````````````````````` example
1241	### foo ###
1242	.
1243	<h3>foo</h3>
1244	````````````````````````````````
1245
1246
1247	A sequence of `#` characters with anything but spaces or tabs following it
1248	is not a closing sequence, but counts as part of the contents of the
1249	heading:
1250
1251	```````````````````````````````` example
1252	### foo ### b
1253	.
1254	<h3>foo ### b</h3>
1255	````````````````````````````````
1256
1257
1258	The closing sequence must be preceded by a space or tab:
1259
1260	```````````````````````````````` example
1261	# foo#
1262	.
1263	<h1>foo#</h1>
1264	````````````````````````````````
1265
1266
1267	Backslash-escaped `#` characters do not count as part
1268	of the closing sequence:
1269
1270	```````````````````````````````` example
1271	### foo \###
1272	## foo #\##
1273	# foo \#
1274	.
1275	<h3>foo ###</h3>
1276	<h2>foo ###</h2>
1277	<h1>foo #</h1>
1278	````````````````````````````````
1279
1280
1281	ATX headings need not be separated from surrounding content by blank
1282	lines, and they can interrupt paragraphs:
1283
1284	```````````````````````````````` example
1285	****
1286	## foo
1287	****
1288	.
1289	<hr />
1290	<h2>foo</h2>
1291	<hr />
1292	````````````````````````````````
1293
1294
1295	```````````````````````````````` example
1296	Foo bar
1297	# baz
1298	Bar foo
1299	.
1300	<p>Foo bar</p>
1301	<h1>baz</h1>
1302	<p>Bar foo</p>
1303	````````````````````````````````
1304
1305
1306	ATX headings can be empty:
1307
1308	```````````````````````````````` example
1309	##
1310	#
1311	### ###
1312	.
1313	<h2></h2>
1314	<h1></h1>
1315	<h3></h3>
1316	````````````````````````````````
1317
1318
1319	## Setext headings
1320
1321	A [setext heading](@) consists of one or more
1322	lines of text, not interrupted by a blank line, of which the first line does not
1323	have more than 3 spaces of indentation, followed by
1324	a [setext heading underline]. The lines of text must be such
1325	that, were they not followed by the setext heading underline,
1326	they would be interpreted as a paragraph: they cannot be
1327	interpretable as a [code fence], [ATX heading][ATX headings],
1328	[block quote][block quotes], [thematic break][thematic breaks],
1329	[list item][list items], or [HTML block][HTML blocks].
1330
1331	A [setext heading underline](@) is a sequence of
1332	`=` characters or a sequence of `-` characters, with no more than 3
1333	spaces of indentation and any number of trailing spaces or tabs. If a line
1334	containing a single `-` can be interpreted as an
1335	empty [list items], it should be interpreted this way
1336	and not as a [setext heading underline].
1337
1338	The heading is a level 1 heading if `=` characters are used in
1339	the [setext heading underline], and a level 2 heading if `-`
1340	characters are used. The contents of the heading are the result
1341	of parsing the preceding lines of text as CommonMark inline
1342	content.
1343
1344	In general, a setext heading need not be preceded or followed by a
1345	blank line. However, it cannot interrupt a paragraph, so when a
1346	setext heading comes after a paragraph, a blank line is needed between
1347	them.
1348
1349	Simple examples:
1350
1351	```````````````````````````````` example
1352	Foo *bar*
1353	=========
1354
1355	Foo *bar*
1356	---------
1357	.
1358	<h1>Foo <em>bar</em></h1>
1359	<h2>Foo <em>bar</em></h2>
1360	````````````````````````````````
1361
1362
1363	The content of the header may span more than one line:
1364
1365	```````````````````````````````` example
1366	Foo *bar
1367	baz*
1368	====
1369	.
1370	<h1>Foo <em>bar
1371	baz</em></h1>
1372	````````````````````````````````
1373
1374	The contents are the result of parsing the headings's raw
1375	content as inlines. The heading's raw content is formed by
1376	concatenating the lines and removing initial and final
1377	spaces or tabs.
1378
1379	```````````````````````````````` example
1380	Foo *bar
1381	baz*→
1382	====
1383	.
1384	<h1>Foo <em>bar
1385	baz</em></h1>
1386	````````````````````````````````
1387
1388
1389	The underlining can be any length:
1390
1391	```````````````````````````````` example
1392	Foo
1393	-------------------------
1394
1395	Foo
1396	=
1397	.
1398	<h2>Foo</h2>
1399	<h1>Foo</h1>
1400	````````````````````````````````
1401
1402
1403	The heading content can be preceded by up to three spaces of indentation, and
1404	need not line up with the underlining:
1405
1406	```````````````````````````````` example
1407	Foo
1408	---
1409
1410	Foo
1411	-----
1412
1413	Foo
1414	===
1415	.
1416	<h2>Foo</h2>
1417	<h2>Foo</h2>
1418	<h1>Foo</h1>
1419	````````````````````````````````
1420
1421
1422	Four spaces of indentation is too many:
1423
1424	```````````````````````````````` example
1425	Foo
1426	---
1427
1428	Foo
1429	---
1430	.
1431	<pre><code>Foo
1432	---
1433
1434	Foo
1435	</code></pre>
1436	<hr />
1437	````````````````````````````````
1438
1439
1440	The setext heading underline can be preceded by up to three spaces of
1441	indentation, and may have trailing spaces or tabs:
1442
1443	```````````````````````````````` example
1444	Foo
1445	----
1446	.
1447	<h2>Foo</h2>
1448	````````````````````````````````
1449
1450
1451	Four spaces of indentation is too many:
1452
1453	```````````````````````````````` example
1454	Foo
1455	---
1456	.
1457	<p>Foo
1458	---</p>
1459	````````````````````````````````
1460
1461
1462	The setext heading underline cannot contain internal spaces or tabs:
1463
1464	```````````````````````````````` example
1465	Foo
1466	= =
1467
1468	Foo
1469	--- -
1470	.
1471	<p>Foo
1472	= =</p>
1473	<p>Foo</p>
1474	<hr />
1475	````````````````````````````````
1476
1477
1478	Trailing spaces or tabs in the content line do not cause a hard line break:
1479
1480	```````````````````````````````` example
1481	Foo
1482	-----
1483	.
1484	<h2>Foo</h2>
1485	````````````````````````````````
1486
1487
1488	Nor does a backslash at the end:
1489
1490	```````````````````````````````` example
1491	Foo\
1492	----
1493	.
1494	<h2>Foo\</h2>
1495	````````````````````````````````
1496
1497
1498	Since indicators of block structure take precedence over
1499	indicators of inline structure, the following are setext headings:
1500
1501	```````````````````````````````` example
1502	`Foo
1503	----
1504	`
1505
1506	<a title="a lot
1507	---
1508	of dashes"/>
1509	.
1510	<h2>`Foo</h2>
1511	<p>`</p>
1512	<h2>&lt;a title=&quot;a lot</h2>
1513	<p>of dashes&quot;/&gt;</p>
1514	````````````````````````````````
1515
1516
1517	The setext heading underline cannot be a [lazy continuation
1518	line] in a list item or block quote:
1519
1520	```````````````````````````````` example
1521	> Foo
1522	---
1523	.
1524	<blockquote>
1525	<p>Foo</p>
1526	</blockquote>
1527	<hr />
1528	````````````````````````````````
1529
1530
1531	```````````````````````````````` example
1532	> foo
1533	bar
1534	===
1535	.
1536	<blockquote>
1537	<p>foo
1538	bar
1539	===</p>
1540	</blockquote>
1541	````````````````````````````````
1542
1543
1544	```````````````````````````````` example
1545	- Foo
1546	---
1547	.
1548	<ul>
1549	<li>Foo</li>
1550	</ul>
1551	<hr />
1552	````````````````````````````````
1553
1554
1555	A blank line is needed between a paragraph and a following
1556	setext heading, since otherwise the paragraph becomes part
1557	of the heading's content:
1558
1559	```````````````````````````````` example
1560	Foo
1561	Bar
1562	---
1563	.
1564	<h2>Foo
1565	Bar</h2>
1566	````````````````````````````````
1567
1568
1569	But in general a blank line is not required before or after
1570	setext headings:
1571
1572	```````````````````````````````` example
1573	---
1574	Foo
1575	---
1576	Bar
1577	---
1578	Baz
1579	.
1580	<hr />
1581	<h2>Foo</h2>
1582	<h2>Bar</h2>
1583	<p>Baz</p>
1584	````````````````````````````````
1585
1586
1587	Setext headings cannot be empty:
1588
1589	```````````````````````````````` example
1590
1591	====
1592	.
1593	<p>====</p>
1594	````````````````````````````````
1595
1596
1597	Setext heading text lines must not be interpretable as block
1598	constructs other than paragraphs. So, the line of dashes
1599	in these examples gets interpreted as a thematic break:
1600
1601	```````````````````````````````` example
1602	---
1603	---
1604	.
1605	<hr />
1606	<hr />
1607	````````````````````````````````
1608
1609
1610	```````````````````````````````` example
1611	- foo
1612	-----
1613	.
1614	<ul>
1615	<li>foo</li>
1616	</ul>
1617	<hr />
1618	````````````````````````````````
1619
1620
1621	```````````````````````````````` example
1622	foo
1623	---
1624	.
1625	<pre><code>foo
1626	</code></pre>
1627	<hr />
1628	````````````````````````````````
1629
1630
1631	```````````````````````````````` example
1632	> foo
1633	-----
1634	.
1635	<blockquote>
1636	<p>foo</p>
1637	</blockquote>
1638	<hr />
1639	````````````````````````````````
1640
1641
1642	If you want a heading with `> foo` as its literal text, you can
1643	use backslash escapes:
1644
1645	```````````````````````````````` example
1646	\> foo
1647	------
1648	.
1649	<h2>&gt; foo</h2>
1650	````````````````````````````````
1651
1652
1653	**Compatibility note:** Most existing Markdown implementations
1654	do not allow the text of setext headings to span multiple lines.
1655	But there is no consensus about how to interpret
1656
1657	``` markdown
1658	Foo
1659	bar
1660	---
1661	baz
1662	```
1663
1664	One can find four different interpretations:
1665
1666	1. paragraph "Foo", heading "bar", paragraph "baz"
1667	2. paragraph "Foo bar", thematic break, paragraph "baz"
1668	3. paragraph "Foo bar --- baz"
1669	4. heading "Foo bar", paragraph "baz"
1670
1671	We find interpretation 4 most natural, and interpretation 4
1672	increases the expressive power of CommonMark, by allowing
1673	multiline headings. Authors who want interpretation 1 can
1674	put a blank line after the first paragraph:
1675
1676	```````````````````````````````` example
1677	Foo
1678
1679	bar
1680	---
1681	baz
1682	.
1683	<p>Foo</p>
1684	<h2>bar</h2>
1685	<p>baz</p>
1686	````````````````````````````````
1687
1688
1689	Authors who want interpretation 2 can put blank lines around
1690	the thematic break,
1691
1692	```````````````````````````````` example
1693	Foo
1694	bar
1695
1696	---
1697
1698	baz
1699	.
1700	<p>Foo
1701	bar</p>
1702	<hr />
1703	<p>baz</p>
1704	````````````````````````````````
1705
1706
1707	or use a thematic break that cannot count as a [setext heading
1708	underline], such as
1709
1710	```````````````````````````````` example
1711	Foo
1712	bar
1713	* * *
1714	baz
1715	.
1716	<p>Foo
1717	bar</p>
1718	<hr />
1719	<p>baz</p>
1720	````````````````````````````````
1721
1722
1723	Authors who want interpretation 3 can use backslash escapes:
1724
1725	```````````````````````````````` example
1726	Foo
1727	bar
1728	\---
1729	baz
1730	.
1731	<p>Foo
1732	bar
1733	---
1734	baz</p>
1735	````````````````````````````````
1736
1737
1738	## Indented code blocks
1739
1740	An [indented code block](@) is composed of one or more
1741	[indented chunks] separated by blank lines.
1742	An [indented chunk](@) is a sequence of non-blank lines,
1743	each preceded by four or more spaces of indentation. The contents of the code
1744	block are the literal contents of the lines, including trailing
1745	[line endings], minus four spaces of indentation.
1746	An indented code block has no [info string].
1747
1748	An indented code block cannot interrupt a paragraph, so there must be
1749	a blank line between a paragraph and a following indented code block.
1750	(A blank line is not needed, however, between a code block and a following
1751	paragraph.)
1752
1753	```````````````````````````````` example
1754	a simple
1755	indented code block
1756	.
1757	<pre><code>a simple
1758	indented code block
1759	</code></pre>
1760	````````````````````````````````
1761
1762
1763	If there is any ambiguity between an interpretation of indentation
1764	as a code block and as indicating that material belongs to a [list
1765	item][list items], the list item interpretation takes precedence:
1766
1767	```````````````````````````````` example
1768	- foo
1769
1770	bar
1771	.
1772	<ul>
1773	<li>
1774	<p>foo</p>
1775	<p>bar</p>
1776	</li>
1777	</ul>
1778	````````````````````````````````
1779
1780
1781	```````````````````````````````` example
1782	1. foo
1783
1784	- bar
1785	.
1786	<ol>
1787	<li>
1788	<p>foo</p>
1789	<ul>
1790	<li>bar</li>
1791	</ul>
1792	</li>
1793	</ol>
1794	````````````````````````````````
1795
1796
1797
1798	The contents of a code block are literal text, and do not get parsed
1799	as Markdown:
1800
1801	```````````````````````````````` example
1802	<a/>
1803	*hi*
1804
1805	- one
1806	.
1807	<pre><code>&lt;a/&gt;
1808	*hi*
1809
1810	- one
1811	</code></pre>
1812	````````````````````````````````
1813
1814
1815	Here we have three chunks separated by blank lines:
1816
1817	```````````````````````````````` example
1818	chunk1
1819
1820	chunk2
1821
1822
1823
1824	chunk3
1825	.
1826	<pre><code>chunk1
1827
1828	chunk2
1829
1830
1831
1832	chunk3
1833	</code></pre>
1834	````````````````````````````````
1835
1836
1837	Any initial spaces or tabs beyond four spaces of indentation will be included in
1838	the content, even in interior blank lines:
1839
1840	```````````````````````````````` example
1841	chunk1
1842
1843	chunk2
1844	.
1845	<pre><code>chunk1
1846
1847	chunk2
1848	</code></pre>
1849	````````````````````````````````
1850
1851
1852	An indented code block cannot interrupt a paragraph. (This
1853	allows hanging indents and the like.)
1854
1855	```````````````````````````````` example
1856	Foo
1857	bar
1858
1859	.
1860	<p>Foo
1861	bar</p>
1862	````````````````````````````````
1863
1864
1865	However, any non-blank line with fewer than four spaces of indentation ends
1866	the code block immediately. So a paragraph may occur immediately
1867	after indented code:
1868
1869	```````````````````````````````` example
1870	foo
1871	bar
1872	.
1873	<pre><code>foo
1874	</code></pre>
1875	<p>bar</p>
1876	````````````````````````````````
1877
1878
1879	And indented code can occur immediately before and after other kinds of
1880	blocks:
1881
1882	```````````````````````````````` example
1883	# Heading
1884	foo
1885	Heading
1886	------
1887	foo
1888	----
1889	.
1890	<h1>Heading</h1>
1891	<pre><code>foo
1892	</code></pre>
1893	<h2>Heading</h2>
1894	<pre><code>foo
1895	</code></pre>
1896	<hr />
1897	````````````````````````````````
1898
1899
1900	The first line can be preceded by more than four spaces of indentation:
1901
1902	```````````````````````````````` example
1903	foo
1904	bar
1905	.
1906	<pre><code> foo
1907	bar
1908	</code></pre>
1909	````````````````````````````````
1910
1911
1912	Blank lines preceding or following an indented code block
1913	are not included in it:
1914
1915	```````````````````````````````` example
1916
1917
1918	foo
1919
1920
1921	.
1922	<pre><code>foo
1923	</code></pre>
1924	````````````````````````````````
1925
1926
1927	Trailing spaces or tabs are included in the code block's content:
1928
1929	```````````````````````````````` example
1930	foo
1931	.
1932	<pre><code>foo
1933	</code></pre>
1934	````````````````````````````````
1935
1936
1937
1938	## Fenced code blocks
1939
1940	A [code fence](@) is a sequence
1941	of at least three consecutive backtick characters (`` ` ``) or
1942	tildes (`~`). (Tildes and backticks cannot be mixed.)
1943	A [fenced code block](@)
1944	begins with a code fence, preceded by up to three spaces of indentation.
1945
1946	The line with the opening code fence may optionally contain some text
1947	following the code fence; this is trimmed of leading and trailing
1948	spaces or tabs and called the [info string](@). If the [info string] comes
1949	after a backtick fence, it may not contain any backtick
1950	characters. (The reason for this restriction is that otherwise
1951	some inline code would be incorrectly interpreted as the
1952	beginning of a fenced code block.)
1953
1954	The content of the code block consists of all subsequent lines, until
1955	a closing [code fence] of the same type as the code block
1956	began with (backticks or tildes), and with at least as many backticks
1957	or tildes as the opening code fence. If the leading code fence is
1958	preceded by N spaces of indentation, then up to N spaces of indentation are
1959	removed from each line of the content (if present). (If a content line is not
1960	indented, it is preserved unchanged. If it is indented N spaces or less, all
1961	of the indentation is removed.)
1962
1963	The closing code fence may be preceded by up to three spaces of indentation, and
1964	may be followed only by spaces or tabs, which are ignored. If the end of the
1965	containing block (or document) is reached and no closing code fence
1966	has been found, the code block contains all of the lines after the
1967	opening code fence until the end of the containing block (or
1968	document). (An alternative spec would require backtracking in the
1969	event that a closing code fence is not found. But this makes parsing
1970	much less efficient, and there seems to be no real down side to the
1971	behavior described here.)
1972
1973	A fenced code block may interrupt a paragraph, and does not require
1974	a blank line either before or after.
1975
1976	The content of a code fence is treated as literal text, not parsed
1977	as inlines. The first word of the [info string] is typically used to
1978	specify the language of the code sample, and rendered in the `class`
1979	attribute of the `code` tag. However, this spec does not mandate any
1980	particular treatment of the [info string].
1981
1982	Here is a simple example with backticks:
1983
1984	```````````````````````````````` example
1985	```
1986	<
1987	>
1988	```
1989	.
1990	<pre><code>&lt;
1991	&gt;
1992	</code></pre>
1993	````````````````````````````````
1994
1995
1996	With tildes:
1997
1998	```````````````````````````````` example
1999	~~~
2000	<
2001	>
2002	~~~
2003	.
2004	<pre><code>&lt;
2005	&gt;
2006	</code></pre>
2007	````````````````````````````````
2008
2009	Fewer than three backticks is not enough:
2010
2011	```````````````````````````````` example
2012	``
2013	foo
2014	``
2015	.
2016	<p><code>foo</code></p>
2017	````````````````````````````````
2018
2019	The closing code fence must use the same character as the opening
2020	fence:
2021
2022	```````````````````````````````` example
2023	```
2024	aaa
2025	~~~
2026	```
2027	.
2028	<pre><code>aaa
2029	~~~
2030	</code></pre>
2031	````````````````````````````````
2032
2033
2034	```````````````````````````````` example
2035	~~~
2036	aaa
2037	```
2038	~~~
2039	.
2040	<pre><code>aaa
2041	```
2042	</code></pre>
2043	````````````````````````````````
2044
2045
2046	The closing code fence must be at least as long as the opening fence:
2047
2048	```````````````````````````````` example
2049	````
2050	aaa
2051	```
2052	``````
2053	.
2054	<pre><code>aaa
2055	```
2056	</code></pre>
2057	````````````````````````````````
2058
2059
2060	```````````````````````````````` example
2061	~~~~
2062	aaa
2063	~~~
2064	~~~~
2065	.
2066	<pre><code>aaa
2067	~~~
2068	</code></pre>
2069	````````````````````````````````
2070
2071
2072	Unclosed code blocks are closed by the end of the document
2073	(or the enclosing [block quote][block quotes] or [list item][list items]):
2074
2075	```````````````````````````````` example
2076	```
2077	.
2078	<pre><code></code></pre>
2079	````````````````````````````````
2080
2081
2082	```````````````````````````````` example
2083	`````
2084
2085	```
2086	aaa
2087	.
2088	<pre><code>
2089	```
2090	aaa
2091	</code></pre>
2092	````````````````````````````````
2093
2094
2095	```````````````````````````````` example
2096	> ```
2097	> aaa
2098
2099	bbb
2100	.
2101	<blockquote>
2102	<pre><code>aaa
2103	</code></pre>
2104	</blockquote>
2105	<p>bbb</p>
2106	````````````````````````````````
2107
2108
2109	A code block can have all empty lines as its content:
2110
2111	```````````````````````````````` example
2112	```
2113
2114
2115	```
2116	.
2117	<pre><code>
2118
2119	</code></pre>
2120	````````````````````````````````
2121
2122
2123	A code block can be empty:
2124
2125	```````````````````````````````` example
2126	```
2127	```
2128	.
2129	<pre><code></code></pre>
2130	````````````````````````````````
2131
2132
2133	Fences can be indented. If the opening fence is indented,
2134	content lines will have equivalent opening indentation removed,
2135	if present:
2136
2137	```````````````````````````````` example
2138	```
2139	aaa
2140	aaa
2141	```
2142	.
2143	<pre><code>aaa
2144	aaa
2145	</code></pre>
2146	````````````````````````````````
2147
2148
2149	```````````````````````````````` example
2150	```
2151	aaa
2152	aaa
2153	aaa
2154	```
2155	.
2156	<pre><code>aaa
2157	aaa
2158	aaa
2159	</code></pre>
2160	````````````````````````````````
2161
2162
2163	```````````````````````````````` example
2164	```
2165	aaa
2166	aaa
2167	aaa
2168	```
2169	.
2170	<pre><code>aaa
2171	aaa
2172	aaa
2173	</code></pre>
2174	````````````````````````````````
2175
2176
2177	Four spaces of indentation is too many:
2178
2179	```````````````````````````````` example
2180	```
2181	aaa
2182	```
2183	.
2184	<pre><code>```
2185	aaa
2186	```
2187	</code></pre>
2188	````````````````````````````````
2189
2190
2191	Closing fences may be preceded by up to three spaces of indentation, and their
2192	indentation need not match that of the opening fence:
2193
2194	```````````````````````````````` example
2195	```
2196	aaa
2197	```
2198	.
2199	<pre><code>aaa
2200	</code></pre>
2201	````````````````````````````````
2202
2203
2204	```````````````````````````````` example
2205	```
2206	aaa
2207	```
2208	.
2209	<pre><code>aaa
2210	</code></pre>
2211	````````````````````````````````
2212
2213
2214	This is not a closing fence, because it is indented 4 spaces:
2215
2216	```````````````````````````````` example
2217	```
2218	aaa
2219	```
2220	.
2221	<pre><code>aaa
2222	```
2223	</code></pre>
2224	````````````````````````````````
2225
2226
2227
2228	Code fences (opening and closing) cannot contain internal spaces or tabs:
2229
2230	```````````````````````````````` example
2231	``` ```
2232	aaa
2233	.
2234	<p><code> </code>
2235	aaa</p>
2236	````````````````````````````````
2237
2238
2239	```````````````````````````````` example
2240	~~~~~~
2241	aaa
2242	~~~ ~~
2243	.
2244	<pre><code>aaa
2245	~~~ ~~
2246	</code></pre>
2247	````````````````````````````````
2248
2249
2250	Fenced code blocks can interrupt paragraphs, and can be followed
2251	directly by paragraphs, without a blank line between:
2252
2253	```````````````````````````````` example
2254	foo
2255	```
2256	bar
2257	```
2258	baz
2259	.
2260	<p>foo</p>
2261	<pre><code>bar
2262	</code></pre>
2263	<p>baz</p>
2264	````````````````````````````````
2265
2266
2267	Other blocks can also occur before and after fenced code blocks
2268	without an intervening blank line:
2269
2270	```````````````````````````````` example
2271	foo
2272	---
2273	~~~
2274	bar
2275	~~~
2276	# baz
2277	.
2278	<h2>foo</h2>
2279	<pre><code>bar
2280	</code></pre>
2281	<h1>baz</h1>
2282	````````````````````````````````
2283
2284
2285	An [info string] can be provided after the opening code fence.
2286	Although this spec doesn't mandate any particular treatment of
2287	the info string, the first word is typically used to specify
2288	the language of the code block. In HTML output, the language is
2289	normally indicated by adding a class to the `code` element consisting
2290	of `language-` followed by the language name.
2291
2292	```````````````````````````````` example
2293	```ruby
2294	def foo(x)
2295	return 3
2296	end
2297	```
2298	.
2299	<pre><code class="language-ruby">def foo(x)
2300	return 3
2301	end
2302	</code></pre>
2303	````````````````````````````````
2304
2305
2306	```````````````````````````````` example
2307	~~~~ ruby startline=3 $%@#$
2308	def foo(x)
2309	return 3
2310	end
2311	~~~~~~~
2312	.
2313	<pre><code class="language-ruby">def foo(x)
2314	return 3
2315	end
2316	</code></pre>
2317	````````````````````````````````
2318
2319
2320	```````````````````````````````` example
2321	````;
2322	````
2323	.
2324	<pre><code class="language-;"></code></pre>
2325	````````````````````````````````
2326
2327
2328	[Info strings] for backtick code blocks cannot contain backticks:
2329
2330	```````````````````````````````` example
2331	``` aa ```
2332	foo
2333	.
2334	<p><code>aa</code>
2335	foo</p>
2336	````````````````````````````````
2337
2338
2339	[Info strings] for tilde code blocks can contain backticks and tildes:
2340
2341	```````````````````````````````` example
2342	~~~ aa ``` ~~~
2343	foo
2344	~~~
2345	.
2346	<pre><code class="language-aa">foo
2347	</code></pre>
2348	````````````````````````````````
2349
2350
2351	Closing code fences cannot have [info strings]:
2352
2353	```````````````````````````````` example
2354	```
2355	``` aaa
2356	```
2357	.
2358	<pre><code>``` aaa
2359	</code></pre>
2360	````````````````````````````````
2361
2362
2363
2364	## HTML blocks
2365
2366	An [HTML block](@) is a group of lines that is treated
2367	as raw HTML (and will not be escaped in HTML output).
2368
2369	There are seven kinds of [HTML block], which can be defined by their
2370	start and end conditions. The block begins with a line that meets a
2371	[start condition](@) (after up to three optional spaces of indentation).
2372	It ends with the first subsequent line that meets a matching
2373	[end condition](@), or the last line of the document, or the last line of
2374	the [container block](#container-blocks) containing the current HTML
2375	block, if no line is encountered that meets the [end condition]. If
2376	the first line meets both the [start condition] and the [end
2377	condition], the block will contain just that line.
2378
2379	1. **Start condition:** line begins with the string `<pre`,
2380	`<script`, `<style`, or `<textarea` (case-insensitive), followed by a space,
2381	a tab, the string `>`, or the end of the line.\
2382	**End condition:** line contains an end tag
2383	`</pre>`, `</script>`, `</style>`, or `</textarea>` (case-insensitive; it
2384	need not match the start tag).
2385
2386	2. **Start condition:** line begins with the string `<!--`.\
2387	**End condition:** line contains the string `-->`.
2388
2389	3. **Start condition:** line begins with the string `<?`.\
2390	**End condition:** line contains the string `?>`.
2391
2392	4. **Start condition:** line begins with the string `<!`
2393	followed by an ASCII letter.\
2394	**End condition:** line contains the character `>`.
2395
2396	5. **Start condition:** line begins with the string
2397	`<![CDATA[`.\
2398	**End condition:** line contains the string `]]>`.
2399
2400	6. **Start condition:** line begins the string `<` or `</`
2401	followed by one of the strings (case-insensitive) `address`,
2402	`article`, `aside`, `base`, `basefont`, `blockquote`, `body`,
2403	`caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`,
2404	`dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`,
2405	`footer`, `form`, `frame`, `frameset`,
2406	`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hr`,
2407	`html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`,
2408	`nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`,
2409	`section`, `source`, `summary`, `table`, `tbody`, `td`,
2410	`tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed
2411	by a space, a tab, the end of the line, the string `>`, or
2412	the string `/>`.\
2413	**End condition:** line is followed by a [blank line].
2414
2415	7. **Start condition:** line begins with a complete [open tag]
2416	(with any [tag name] other than `pre`, `script`,
2417	`style`, or `textarea`) or a complete [closing tag],
2418	followed by zero or more spaces and tabs, followed by the end of the line.\
2419	**End condition:** line is followed by a [blank line].
2420
2421	HTML blocks continue until they are closed by their appropriate
2422	[end condition], or the last line of the document or other [container
2423	block](#container-blocks). This means any HTML **within an HTML
2424	block** that might otherwise be recognised as a start condition will
2425	be ignored by the parser and passed through as-is, without changing
2426	the parser's state.
2427
2428	For instance, `<pre>` within an HTML block started by `<table>` will not affect
2429	the parser state; as the HTML block was started in by start condition 6, it
2430	will end at any blank line. This can be surprising:
2431
2432	```````````````````````````````` example
2433	<table><tr><td>
2434	<pre>
2435	**Hello**,
2436
2437	_world_.
2438	</pre>
2439	</td></tr></table>
2440	.
2441	<table><tr><td>
2442	<pre>
2443	**Hello**,
2444	<p><em>world</em>.
2445	</pre></p>
2446	</td></tr></table>
2447	````````````````````````````````
2448
2449	In this case, the HTML block is terminated by the blank line — the `**Hello**`
2450	text remains verbatim — and regular parsing resumes, with a paragraph,
2451	emphasised `world` and inline and block HTML following.
2452
2453	All types of [HTML blocks] except type 7 may interrupt
2454	a paragraph. Blocks of type 7 may not interrupt a paragraph.
2455	(This restriction is intended to prevent unwanted interpretation
2456	of long tags inside a wrapped paragraph as starting HTML blocks.)
2457
2458	Some simple examples follow. Here are some basic HTML blocks
2459	of type 6:
2460
2461	```````````````````````````````` example
2462	<table>
2463	<tr>
2464	<td>
2465	hi
2466	</td>
2467	</tr>
2468	</table>
2469
2470	okay.
2471	.
2472	<table>
2473	<tr>
2474	<td>
2475	hi
2476	</td>
2477	</tr>
2478	</table>
2479	<p>okay.</p>
2480	````````````````````````````````
2481
2482
2483	```````````````````````````````` example
2484	<div>
2485	*hello*
2486	<foo><a>
2487	.
2488	<div>
2489	*hello*
2490	<foo><a>
2491	````````````````````````````````
2492
2493
2494	A block can also start with a closing tag:
2495
2496	```````````````````````````````` example
2497	</div>
2498	*foo*
2499	.
2500	</div>
2501	*foo*
2502	````````````````````````````````
2503
2504
2505	Here we have two HTML blocks with a Markdown paragraph between them:
2506
2507	```````````````````````````````` example
2508	<DIV CLASS="foo">
2509
2510	*Markdown*
2511
2512	</DIV>
2513	.
2514	<DIV CLASS="foo">
2515	<p><em>Markdown</em></p>
2516	</DIV>
2517	````````````````````````````````
2518
2519
2520	The tag on the first line can be partial, as long
2521	as it is split where there would be whitespace:
2522
2523	```````````````````````````````` example
2524	<div id="foo"
2525	class="bar">
2526	</div>
2527	.
2528	<div id="foo"
2529	class="bar">
2530	</div>
2531	````````````````````````````````
2532
2533
2534	```````````````````````````````` example
2535	<div id="foo" class="bar
2536	baz">
2537	</div>
2538	.
2539	<div id="foo" class="bar
2540	baz">
2541	</div>
2542	````````````````````````````````
2543
2544
2545	An open tag need not be closed:
2546	```````````````````````````````` example
2547	<div>
2548	*foo*
2549
2550	*bar*
2551	.
2552	<div>
2553	*foo*
2554	<p><em>bar</em></p>
2555	````````````````````````````````
2556
2557
2558
2559	A partial tag need not even be completed (garbage
2560	in, garbage out):
2561
2562	```````````````````````````````` example
2563	<div id="foo"
2564	*hi*
2565	.
2566	<div id="foo"
2567	*hi*
2568	````````````````````````````````
2569
2570
2571	```````````````````````````````` example
2572	<div class
2573	foo
2574	.
2575	<div class
2576	foo
2577	````````````````````````````````
2578
2579
2580	The initial tag doesn't even need to be a valid
2581	tag, as long as it starts like one:
2582
2583	```````````````````````````````` example
2584	<div *???-&&&-<---
2585	*foo*
2586	.
2587	<div *???-&&&-<---
2588	*foo*
2589	````````````````````````````````
2590
2591
2592	In type 6 blocks, the initial tag need not be on a line by
2593	itself:
2594
2595	```````````````````````````````` example
2596	<div><a href="bar">*foo*</a></div>
2597	.
2598	<div><a href="bar">*foo*</a></div>
2599	````````````````````````````````
2600
2601
2602	```````````````````````````````` example
2603	<table><tr><td>
2604	foo
2605	</td></tr></table>
2606	.
2607	<table><tr><td>
2608	foo
2609	</td></tr></table>
2610	````````````````````````````````
2611
2612
2613	Everything until the next blank line or end of document
2614	gets included in the HTML block. So, in the following
2615	example, what looks like a Markdown code block
2616	is actually part of the HTML block, which continues until a blank
2617	line or the end of the document is reached:
2618
2619	```````````````````````````````` example
2620	<div></div>
2621	``` c
2622	int x = 33;
2623	```
2624	.
2625	<div></div>
2626	``` c
2627	int x = 33;
2628	```
2629	````````````````````````````````
2630
2631
2632	To start an [HTML block] with a tag that is *not* in the
2633	list of block-level tags in (6), you must put the tag by
2634	itself on the first line (and it must be complete):
2635
2636	```````````````````````````````` example
2637	<a href="foo">
2638	*bar*
2639	</a>
2640	.
2641	<a href="foo">
2642	*bar*
2643	</a>
2644	````````````````````````````````
2645
2646
2647	In type 7 blocks, the [tag name] can be anything:
2648
2649	```````````````````````````````` example
2650	<Warning>
2651	*bar*
2652	</Warning>
2653	.
2654	<Warning>
2655	*bar*
2656	</Warning>
2657	````````````````````````````````
2658
2659
2660	```````````````````````````````` example
2661	<i class="foo">
2662	*bar*
2663	</i>
2664	.
2665	<i class="foo">
2666	*bar*
2667	</i>
2668	````````````````````````````````
2669
2670
2671	```````````````````````````````` example
2672	</ins>
2673	*bar*
2674	.
2675	</ins>
2676	*bar*
2677	````````````````````````````````
2678
2679
2680	These rules are designed to allow us to work with tags that
2681	can function as either block-level or inline-level tags.
2682	The `<del>` tag is a nice example. We can surround content with
2683	`<del>` tags in three different ways. In this case, we get a raw
2684	HTML block, because the `<del>` tag is on a line by itself:
2685
2686	```````````````````````````````` example
2687	<del>
2688	*foo*
2689	</del>
2690	.
2691	<del>
2692	*foo*
2693	</del>
2694	````````````````````````````````
2695
2696
2697	In this case, we get a raw HTML block that just includes
2698	the `<del>` tag (because it ends with the following blank
2699	line). So the contents get interpreted as CommonMark:
2700
2701	```````````````````````````````` example
2702	<del>
2703
2704	*foo*
2705
2706	</del>
2707	.
2708	<del>
2709	<p><em>foo</em></p>
2710	</del>
2711	````````````````````````````````
2712
2713
2714	Finally, in this case, the `<del>` tags are interpreted
2715	as [raw HTML] *inside* the CommonMark paragraph. (Because
2716	the tag is not on a line by itself, we get inline HTML
2717	rather than an [HTML block].)
2718
2719	```````````````````````````````` example
2720	<del>*foo*</del>
2721	.
2722	<p><del><em>foo</em></del></p>
2723	````````````````````````````````
2724
2725
2726	HTML tags designed to contain literal content
2727	(`pre`, `script`, `style`, `textarea`), comments, processing instructions,
2728	and declarations are treated somewhat differently.
2729	Instead of ending at the first blank line, these blocks
2730	end at the first line containing a corresponding end tag.
2731	As a result, these blocks can contain blank lines:
2732
2733	A pre tag (type 1):
2734
2735	```````````````````````````````` example
2736	<pre language="haskell"><code>
2737	import Text.HTML.TagSoup
2738
2739	main :: IO ()
2740	main = print $ parseTags tags
2741	</code></pre>
2742	okay
2743	.
2744	<pre language="haskell"><code>
2745	import Text.HTML.TagSoup
2746
2747	main :: IO ()
2748	main = print $ parseTags tags
2749	</code></pre>
2750	<p>okay</p>
2751	````````````````````````````````
2752
2753
2754	A script tag (type 1):
2755
2756	```````````````````````````````` example
2757	<script type="text/javascript">
2758	// JavaScript example
2759
2760	document.getElementById("demo").innerHTML = "Hello JavaScript!";
2761	</script>
2762	okay
2763	.
2764	<script type="text/javascript">
2765	// JavaScript example
2766
2767	document.getElementById("demo").innerHTML = "Hello JavaScript!";
2768	</script>
2769	<p>okay</p>
2770	````````````````````````````````
2771
2772
2773	A textarea tag (type 1):
2774
2775	```````````````````````````````` example
2776	<textarea>
2777
2778	*foo*
2779
2780	_bar_
2781
2782	</textarea>
2783	.
2784	<textarea>
2785
2786	*foo*
2787
2788	_bar_
2789
2790	</textarea>
2791	````````````````````````````````
2792
2793	A style tag (type 1):
2794
2795	```````````````````````````````` example
2796	<style
2797	type="text/css">
2798	h1 {color:red;}
2799
2800	p {color:blue;}
2801	</style>
2802	okay
2803	.
2804	<style
2805	type="text/css">
2806	h1 {color:red;}
2807
2808	p {color:blue;}
2809	</style>
2810	<p>okay</p>
2811	````````````````````````````````
2812
2813
2814	If there is no matching end tag, the block will end at the
2815	end of the document (or the enclosing [block quote][block quotes]
2816	or [list item][list items]):
2817
2818	```````````````````````````````` example
2819	<style
2820	type="text/css">
2821
2822	foo
2823	.
2824	<style
2825	type="text/css">
2826
2827	foo
2828	````````````````````````````````
2829
2830
2831	```````````````````````````````` example
2832	> <div>
2833	> foo
2834
2835	bar
2836	.
2837	<blockquote>
2838	<div>
2839	foo
2840	</blockquote>
2841	<p>bar</p>
2842	````````````````````````````````
2843
2844
2845	```````````````````````````````` example
2846	- <div>
2847	- foo
2848	.
2849	<ul>
2850	<li>
2851	<div>
2852	</li>
2853	<li>foo</li>
2854	</ul>
2855	````````````````````````````````
2856
2857
2858	The end tag can occur on the same line as the start tag:
2859
2860	```````````````````````````````` example
2861	<style>p{color:red;}</style>
2862	*foo*
2863	.
2864	<style>p{color:red;}</style>
2865	<p><em>foo</em></p>
2866	````````````````````````````````
2867
2868
2869	```````````````````````````````` example
2870	<!-- foo -->*bar*
2871	*baz*
2872	.
2873	<!-- foo -->*bar*
2874	<p><em>baz</em></p>
2875	````````````````````````````````
2876
2877
2878	Note that anything on the last line after the
2879	end tag will be included in the [HTML block]:
2880
2881	```````````````````````````````` example
2882	<script>
2883	foo
2884	</script>1. *bar*
2885	.
2886	<script>
2887	foo
2888	</script>1. *bar*
2889	````````````````````````````````
2890
2891
2892	A comment (type 2):
2893
2894	```````````````````````````````` example
2895	<!-- Foo
2896
2897	bar
2898	baz -->
2899	okay
2900	.
2901	<!-- Foo
2902
2903	bar
2904	baz -->
2905	<p>okay</p>
2906	````````````````````````````````
2907
2908
2909
2910	A processing instruction (type 3):
2911
2912	```````````````````````````````` example
2913	<?php
2914
2915	echo '>';
2916
2917	?>
2918	okay
2919	.
2920	<?php
2921
2922	echo '>';
2923
2924	?>
2925	<p>okay</p>
2926	````````````````````````````````
2927
2928
2929	A declaration (type 4):
2930
2931	```````````````````````````````` example
2932	<!DOCTYPE html>
2933	.
2934	<!DOCTYPE html>
2935	````````````````````````````````
2936
2937
2938	CDATA (type 5):
2939
2940	```````````````````````````````` example
2941	<![CDATA[
2942	function matchwo(a,b)
2943	{
2944	if (a < b && a < 0) then {
2945	return 1;
2946
2947	} else {
2948
2949	return 0;
2950	}
2951	}
2952	]]>
2953	okay
2954	.
2955	<![CDATA[
2956	function matchwo(a,b)
2957	{
2958	if (a < b && a < 0) then {
2959	return 1;
2960
2961	} else {
2962
2963	return 0;
2964	}
2965	}
2966	]]>
2967	<p>okay</p>
2968	````````````````````````````````
2969
2970
2971	The opening tag can be preceded by up to three spaces of indentation, but not
2972	four:
2973
2974	```````````````````````````````` example
2975	<!-- foo -->
2976
2977	<!-- foo -->
2978	.
2979	<!-- foo -->
2980	<pre><code>&lt;!-- foo --&gt;
2981	</code></pre>
2982	````````````````````````````````
2983
2984
2985	```````````````````````````````` example
2986	<div>
2987
2988	<div>
2989	.
2990	<div>
2991	<pre><code>&lt;div&gt;
2992	</code></pre>
2993	````````````````````````````````
2994
2995
2996	An HTML block of types 1--6 can interrupt a paragraph, and need not be
2997	preceded by a blank line.
2998
2999	```````````````````````````````` example
3000	Foo
3001	<div>
3002	bar
3003	</div>
3004	.
3005	<p>Foo</p>
3006	<div>
3007	bar
3008	</div>
3009	````````````````````````````````
3010
3011
3012	However, a following blank line is needed, except at the end of
3013	a document, and except for blocks of types 1--5, [above][HTML
3014	block]:
3015
3016	```````````````````````````````` example
3017	<div>
3018	bar
3019	</div>
3020	*foo*
3021	.
3022	<div>
3023	bar
3024	</div>
3025	*foo*
3026	````````````````````````````````
3027
3028
3029	HTML blocks of type 7 cannot interrupt a paragraph:
3030
3031	```````````````````````````````` example
3032	Foo
3033	<a href="bar">
3034	baz
3035	.
3036	<p>Foo
3037	<a href="bar">
3038	baz</p>
3039	````````````````````````````````
3040
3041
3042	This rule differs from John Gruber's original Markdown syntax
3043	specification, which says:
3044
3045	> The only restrictions are that block-level HTML elements —
3046	> e.g. `<div>`, `<table>`, `<pre>`, `<p>`, etc. — must be separated from
3047	> surrounding content by blank lines, and the start and end tags of the
3048	> block should not be indented with spaces or tabs.
3049
3050	In some ways Gruber's rule is more restrictive than the one given
3051	here:
3052
3053	- It requires that an HTML block be preceded by a blank line.
3054	- It does not allow the start tag to be indented.
3055	- It requires a matching end tag, which it also does not allow to
3056	be indented.
3057
3058	Most Markdown implementations (including some of Gruber's own) do not
3059	respect all of these restrictions.
3060
3061	There is one respect, however, in which Gruber's rule is more liberal
3062	than the one given here, since it allows blank lines to occur inside
3063	an HTML block. There are two reasons for disallowing them here.
3064	First, it removes the need to parse balanced tags, which is
3065	expensive and can require backtracking from the end of the document
3066	if no matching end tag is found. Second, it provides a very simple
3067	and flexible way of including Markdown content inside HTML tags:
3068	simply separate the Markdown from the HTML using blank lines:
3069
3070	Compare:
3071
3072	```````````````````````````````` example
3073	<div>
3074
3075	*Emphasized* text.
3076
3077	</div>
3078	.
3079	<div>
3080	<p><em>Emphasized</em> text.</p>
3081	</div>
3082	````````````````````````````````
3083
3084
3085	```````````````````````````````` example
3086	<div>
3087	*Emphasized* text.
3088	</div>
3089	.
3090	<div>
3091	*Emphasized* text.
3092	</div>
3093	````````````````````````````````
3094
3095
3096	Some Markdown implementations have adopted a convention of
3097	interpreting content inside tags as text if the open tag has
3098	the attribute `markdown=1`. The rule given above seems a simpler and
3099	more elegant way of achieving the same expressive power, which is also
3100	much simpler to parse.
3101
3102	The main potential drawback is that one can no longer paste HTML
3103	blocks into Markdown documents with 100% reliability. However,
3104	*in most cases* this will work fine, because the blank lines in
3105	HTML are usually followed by HTML block tags. For example:
3106
3107	```````````````````````````````` example
3108	<table>
3109
3110	<tr>
3111
3112	<td>
3113	Hi
3114	</td>
3115
3116	</tr>
3117
3118	</table>
3119	.
3120	<table>
3121	<tr>
3122	<td>
3123	Hi
3124	</td>
3125	</tr>
3126	</table>
3127	````````````````````````````````
3128
3129
3130	There are problems, however, if the inner tags are indented
3131	*and* separated by spaces, as then they will be interpreted as
3132	an indented code block:
3133
3134	```````````````````````````````` example
3135	<table>
3136
3137	<tr>
3138
3139	<td>
3140	Hi
3141	</td>
3142
3143	</tr>
3144
3145	</table>
3146	.
3147	<table>
3148	<tr>
3149	<pre><code>&lt;td&gt;
3150	Hi
3151	&lt;/td&gt;
3152	</code></pre>
3153	</tr>
3154	</table>
3155	````````````````````````````````
3156
3157
3158	Fortunately, blank lines are usually not necessary and can be
3159	deleted. The exception is inside `<pre>` tags, but as described
3160	[above][HTML blocks], raw HTML blocks starting with `<pre>`
3161	*can* contain blank lines.
3162
3163	## Link reference definitions
3164
3165	A [link reference definition](@)
3166	consists of a [link label], optionally preceded by up to three spaces of
3167	indentation, followed
3168	by a colon (`:`), optional spaces or tabs (including up to one
3169	[line ending]), a [link destination],
3170	optional spaces or tabs (including up to one
3171	[line ending]), and an optional [link
3172	title], which if it is present must be separated
3173	from the [link destination] by spaces or tabs.
3174	No further character may occur.
3175
3176	A [link reference definition]
3177	does not correspond to a structural element of a document. Instead, it
3178	defines a label which can be used in [reference links]
3179	and reference-style [images] elsewhere in the document. [Link
3180	reference definitions] can come either before or after the links that use
3181	them.
3182
3183	```````````````````````````````` example
3184	[foo]: /url "title"
3185
3186	[foo]
3187	.
3188	<p><a href="/url" title="title">foo</a></p>
3189	````````````````````````````````
3190
3191
3192	```````````````````````````````` example
3193	[foo]:
3194	/url
3195	'the title'
3196
3197	[foo]
3198	.
3199	<p><a href="/url" title="the title">foo</a></p>
3200	````````````````````````````````
3201
3202
3203	```````````````````````````````` example
3204	[Foo*bar\]]:my_(url) 'title (with parens)'
3205
3206	[Foo*bar\]]
3207	.
3208	<p><a href="my_(url)" title="title (with parens)">Foo*bar]</a></p>
3209	````````````````````````````````
3210
3211
3212	```````````````````````````````` example
3213	[Foo bar]:
3214	<my url>
3215	'title'
3216
3217	[Foo bar]
3218	.
3219	<p><a href="my%20url" title="title">Foo bar</a></p>
3220	````````````````````````````````
3221
3222
3223	The title may extend over multiple lines:
3224
3225	```````````````````````````````` example
3226	[foo]: /url '
3227	title
3228	line1
3229	line2
3230	'
3231
3232	[foo]
3233	.
3234	<p><a href="/url" title="
3235	title
3236	line1
3237	line2
3238	">foo</a></p>
3239	````````````````````````````````
3240
3241
3242	However, it may not contain a [blank line]:
3243
3244	```````````````````````````````` example
3245	[foo]: /url 'title
3246
3247	with blank line'
3248
3249	[foo]
3250	.
3251	<p>[foo]: /url 'title</p>
3252	<p>with blank line'</p>
3253	<p>[foo]</p>
3254	````````````````````````````````
3255
3256
3257	The title may be omitted:
3258
3259	```````````````````````````````` example
3260	[foo]:
3261	/url
3262
3263	[foo]
3264	.
3265	<p><a href="/url">foo</a></p>
3266	````````````````````````````````
3267
3268
3269	The link destination may not be omitted:
3270
3271	```````````````````````````````` example
3272	[foo]:
3273
3274	[foo]
3275	.
3276	<p>[foo]:</p>
3277	<p>[foo]</p>
3278	````````````````````````````````
3279
3280	However, an empty link destination may be specified using
3281	angle brackets:
3282
3283	```````````````````````````````` example
3284	[foo]: <>
3285
3286	[foo]
3287	.
3288	<p><a href="">foo</a></p>
3289	````````````````````````````````
3290
3291	The title must be separated from the link destination by
3292	spaces or tabs:
3293
3294	```````````````````````````````` example
3295	[foo]: <bar>(baz)
3296
3297	[foo]
3298	.
3299	<p>[foo]: <bar>(baz)</p>
3300	<p>[foo]</p>
3301	````````````````````````````````
3302
3303
3304	Both title and destination can contain backslash escapes
3305	and literal backslashes:
3306
3307	```````````````````````````````` example
3308	[foo]: /url\bar\*baz "foo\"bar\baz"
3309
3310	[foo]
3311	.
3312	<p><a href="/url%5Cbar*baz" title="foo&quot;bar\baz">foo</a></p>
3313	````````````````````````````````
3314
3315
3316	A link can come before its corresponding definition:
3317
3318	```````````````````````````````` example
3319	[foo]
3320
3321	[foo]: url
3322	.
3323	<p><a href="url">foo</a></p>
3324	````````````````````````````````
3325
3326
3327	If there are several matching definitions, the first one takes
3328	precedence:
3329
3330	```````````````````````````````` example
3331	[foo]
3332
3333	[foo]: first
3334	[foo]: second
3335	.
3336	<p><a href="first">foo</a></p>
3337	````````````````````````````````
3338
3339
3340	As noted in the section on [Links], matching of labels is
3341	case-insensitive (see [matches]).
3342
3343	```````````````````````````````` example
3344	[FOO]: /url
3345
3346	[Foo]
3347	.
3348	<p><a href="/url">Foo</a></p>
3349	````````````````````````````````
3350
3351
3352	```````````````````````````````` example
3353	[ΑΓΩ]: /φου
3354
3355	[αγω]
3356	.
3357	<p><a href="/%CF%86%CE%BF%CF%85">αγω</a></p>
3358	````````````````````````````````
3359
3360
3361	Whether something is a [link reference definition] is
3362	independent of whether the link reference it defines is
3363	used in the document. Thus, for example, the following
3364	document contains just a link reference definition, and
3365	no visible content:
3366
3367	```````````````````````````````` example
3368	[foo]: /url
3369	.
3370	````````````````````````````````
3371
3372
3373	Here is another one:
3374
3375	```````````````````````````````` example
3376	[
3377	foo
3378	]: /url
3379	bar
3380	.
3381	<p>bar</p>
3382	````````````````````````````````
3383
3384
3385	This is not a link reference definition, because there are
3386	characters other than spaces or tabs after the title:
3387
3388	```````````````````````````````` example
3389	[foo]: /url "title" ok
3390	.
3391	<p>[foo]: /url &quot;title&quot; ok</p>
3392	````````````````````````````````
3393
3394
3395	This is a link reference definition, but it has no title:
3396
3397	```````````````````````````````` example
3398	[foo]: /url
3399	"title" ok
3400	.
3401	<p>&quot;title&quot; ok</p>
3402	````````````````````````````````
3403
3404
3405	This is not a link reference definition, because it is indented
3406	four spaces:
3407
3408	```````````````````````````````` example
3409	[foo]: /url "title"
3410
3411	[foo]
3412	.
3413	<pre><code>[foo]: /url &quot;title&quot;
3414	</code></pre>
3415	<p>[foo]</p>
3416	````````````````````````````````
3417
3418
3419	This is not a link reference definition, because it occurs inside
3420	a code block:
3421
3422	```````````````````````````````` example
3423	```
3424	[foo]: /url
3425	```
3426
3427	[foo]
3428	.
3429	<pre><code>[foo]: /url
3430	</code></pre>
3431	<p>[foo]</p>
3432	````````````````````````````````
3433
3434
3435	A [link reference definition] cannot interrupt a paragraph.
3436
3437	```````````````````````````````` example
3438	Foo
3439	[bar]: /baz
3440
3441	[bar]
3442	.
3443	<p>Foo
3444	[bar]: /baz</p>
3445	<p>[bar]</p>
3446	````````````````````````````````
3447
3448
3449	However, it can directly follow other block elements, such as headings
3450	and thematic breaks, and it need not be followed by a blank line.
3451
3452	```````````````````````````````` example
3453	# [Foo]
3454	[foo]: /url
3455	> bar
3456	.
3457	<h1><a href="/url">Foo</a></h1>
3458	<blockquote>
3459	<p>bar</p>
3460	</blockquote>
3461	````````````````````````````````
3462
3463	```````````````````````````````` example
3464	[foo]: /url
3465	bar
3466	===
3467	[foo]
3468	.
3469	<h1>bar</h1>
3470	<p><a href="/url">foo</a></p>
3471	````````````````````````````````
3472
3473	```````````````````````````````` example
3474	[foo]: /url
3475	===
3476	[foo]
3477	.
3478	<p>===
3479	<a href="/url">foo</a></p>
3480	````````````````````````````````
3481
3482
3483	Several [link reference definitions]
3484	can occur one after another, without intervening blank lines.
3485
3486	```````````````````````````````` example
3487	[foo]: /foo-url "foo"
3488	[bar]: /bar-url
3489	"bar"
3490	[baz]: /baz-url
3491
3492	[foo],
3493	[bar],
3494	[baz]
3495	.
3496	<p><a href="/foo-url" title="foo">foo</a>,
3497	<a href="/bar-url" title="bar">bar</a>,
3498	<a href="/baz-url">baz</a></p>
3499	````````````````````````````````
3500
3501
3502	[Link reference definitions] can occur
3503	inside block containers, like lists and block quotations. They
3504	affect the entire document, not just the container in which they
3505	are defined:
3506
3507	```````````````````````````````` example
3508	[foo]
3509
3510	> [foo]: /url
3511	.
3512	<p><a href="/url">foo</a></p>
3513	<blockquote>
3514	</blockquote>
3515	````````````````````````````````
3516
3517
3518	## Paragraphs
3519
3520	A sequence of non-blank lines that cannot be interpreted as other
3521	kinds of blocks forms a [paragraph](@).
3522	The contents of the paragraph are the result of parsing the
3523	paragraph's raw content as inlines. The paragraph's raw content
3524	is formed by concatenating the lines and removing initial and final
3525	spaces or tabs.
3526
3527	A simple example with two paragraphs:
3528
3529	```````````````````````````````` example
3530	aaa
3531
3532	bbb
3533	.
3534	<p>aaa</p>
3535	<p>bbb</p>
3536	````````````````````````````````
3537
3538
3539	Paragraphs can contain multiple lines, but no blank lines:
3540
3541	```````````````````````````````` example
3542	aaa
3543	bbb
3544
3545	ccc
3546	ddd
3547	.
3548	<p>aaa
3549	bbb</p>
3550	<p>ccc
3551	ddd</p>
3552	````````````````````````````````
3553
3554
3555	Multiple blank lines between paragraphs have no effect:
3556
3557	```````````````````````````````` example
3558	aaa
3559
3560
3561	bbb
3562	.
3563	<p>aaa</p>
3564	<p>bbb</p>
3565	````````````````````````````````
3566
3567
3568	Leading spaces or tabs are skipped:
3569
3570	```````````````````````````````` example
3571	aaa
3572	bbb
3573	.
3574	<p>aaa
3575	bbb</p>
3576	````````````````````````````````
3577
3578
3579	Lines after the first may be indented any amount, since indented
3580	code blocks cannot interrupt paragraphs.
3581
3582	```````````````````````````````` example
3583	aaa
3584	bbb
3585	ccc
3586	.
3587	<p>aaa
3588	bbb
3589	ccc</p>
3590	````````````````````````````````
3591
3592
3593	However, the first line may be preceded by up to three spaces of indentation.
3594	Four spaces of indentation is too many:
3595
3596	```````````````````````````````` example
3597	aaa
3598	bbb
3599	.
3600	<p>aaa
3601	bbb</p>
3602	````````````````````````````````
3603
3604
3605	```````````````````````````````` example
3606	aaa
3607	bbb
3608	.
3609	<pre><code>aaa
3610	</code></pre>
3611	<p>bbb</p>
3612	````````````````````````````````
3613
3614
3615	Final spaces or tabs are stripped before inline parsing, so a paragraph
3616	that ends with two or more spaces will not end with a [hard line
3617	break]:
3618
3619	```````````````````````````````` example
3620	aaa
3621	bbb
3622	.
3623	<p>aaa<br />
3624	bbb</p>
3625	````````````````````````````````
3626
3627
3628	## Blank lines
3629
3630	[Blank lines] between block-level elements are ignored,
3631	except for the role they play in determining whether a [list]
3632	is [tight] or [loose].
3633
3634	Blank lines at the beginning and end of the document are also ignored.
3635
3636	```````````````````````````````` example
3637
3638
3639	aaa
3640
3641
3642	# aaa
3643
3644
3645	.
3646	<p>aaa</p>
3647	<h1>aaa</h1>
3648	````````````````````````````````
3649
3650
3651
3652	# Container blocks
3653
3654	A [container block](#container-blocks) is a block that has other
3655	blocks as its contents. There are two basic kinds of container blocks:
3656	[block quotes] and [list items].
3657	[Lists] are meta-containers for [list items].
3658
3659	We define the syntax for container blocks recursively. The general
3660	form of the definition is:
3661
3662	> If X is a sequence of blocks, then the result of
3663	> transforming X in such-and-such a way is a container of type Y
3664	> with these blocks as its content.
3665
3666	So, we explain what counts as a block quote or list item by explaining
3667	how these can be *generated* from their contents. This should suffice
3668	to define the syntax, although it does not give a recipe for *parsing*
3669	these constructions. (A recipe is provided below in the section entitled
3670	[A parsing strategy](#appendix-a-parsing-strategy).)
3671
3672	## Block quotes
3673
3674	A [block quote marker](@),
3675	optionally preceded by up to three spaces of indentation,
3676	consists of (a) the character `>` together with a following space of
3677	indentation, or (b) a single character `>` not followed by a space of
3678	indentation.
3679
3680	The following rules define [block quotes]:
3681
3682	1. **Basic case.** If a string of lines *Ls* constitute a sequence
3683	of blocks *Bs*, then the result of prepending a [block quote
3684	marker] to the beginning of each line in *Ls*
3685	is a [block quote](#block-quotes) containing *Bs*.
3686
3687	2. **Laziness.** If a string of lines *Ls* constitute a [block
3688	quote](#block-quotes) with contents *Bs*, then the result of deleting
3689	the initial [block quote marker] from one or
3690	more lines in which the next character other than a space or tab after the
3691	[block quote marker] is [paragraph continuation
3692	text] is a block quote with *Bs* as its content.
3693	[Paragraph continuation text](@) is text
3694	that will be parsed as part of the content of a paragraph, but does
3695	not occur at the beginning of the paragraph.
3696
3697	3. **Consecutiveness.** A document cannot contain two [block
3698	quotes] in a row unless there is a [blank line] between them.
3699
3700	Nothing else counts as a [block quote](#block-quotes).
3701
3702	Here is a simple example:
3703
3704	```````````````````````````````` example
3705	> # Foo
3706	> bar
3707	> baz
3708	.
3709	<blockquote>
3710	<h1>Foo</h1>
3711	<p>bar
3712	baz</p>
3713	</blockquote>
3714	````````````````````````````````
3715
3716
3717	The space or tab after the `>` characters can be omitted:
3718
3719	```````````````````````````````` example
3720	># Foo
3721	>bar
3722	> baz
3723	.
3724	<blockquote>
3725	<h1>Foo</h1>
3726	<p>bar
3727	baz</p>
3728	</blockquote>
3729	````````````````````````````````
3730
3731
3732	The `>` characters can be preceded by up to three spaces of indentation:
3733
3734	```````````````````````````````` example
3735	> # Foo
3736	> bar
3737	> baz
3738	.
3739	<blockquote>
3740	<h1>Foo</h1>
3741	<p>bar
3742	baz</p>
3743	</blockquote>
3744	````````````````````````````````
3745
3746
3747	Four spaces of indentation is too many:
3748
3749	```````````````````````````````` example
3750	> # Foo
3751	> bar
3752	> baz
3753	.
3754	<pre><code>&gt; # Foo
3755	&gt; bar
3756	&gt; baz
3757	</code></pre>
3758	````````````````````````````````
3759
3760
3761	The Laziness clause allows us to omit the `>` before
3762	[paragraph continuation text]:
3763
3764	```````````````````````````````` example
3765	> # Foo
3766	> bar
3767	baz
3768	.
3769	<blockquote>
3770	<h1>Foo</h1>
3771	<p>bar
3772	baz</p>
3773	</blockquote>
3774	````````````````````````````````
3775
3776
3777	A block quote can contain some lazy and some non-lazy
3778	continuation lines:
3779
3780	```````````````````````````````` example
3781	> bar
3782	baz
3783	> foo
3784	.
3785	<blockquote>
3786	<p>bar
3787	baz
3788	foo</p>
3789	</blockquote>
3790	````````````````````````````````
3791
3792
3793	Laziness only applies to lines that would have been continuations of
3794	paragraphs had they been prepended with [block quote markers].
3795	For example, the `> ` cannot be omitted in the second line of
3796
3797	``` markdown
3798	> foo
3799	> ---
3800	```
3801
3802	without changing the meaning:
3803
3804	```````````````````````````````` example
3805	> foo
3806	---
3807	.
3808	<blockquote>
3809	<p>foo</p>
3810	</blockquote>
3811	<hr />
3812	````````````````````````````````
3813
3814
3815	Similarly, if we omit the `> ` in the second line of
3816
3817	``` markdown
3818	> - foo
3819	> - bar
3820	```
3821
3822	then the block quote ends after the first line:
3823
3824	```````````````````````````````` example
3825	> - foo
3826	- bar
3827	.
3828	<blockquote>
3829	<ul>
3830	<li>foo</li>
3831	</ul>
3832	</blockquote>
3833	<ul>
3834	<li>bar</li>
3835	</ul>
3836	````````````````````````````````
3837
3838
3839	For the same reason, we can't omit the `> ` in front of
3840	subsequent lines of an indented or fenced code block:
3841
3842	```````````````````````````````` example
3843	> foo
3844	bar
3845	.
3846	<blockquote>
3847	<pre><code>foo
3848	</code></pre>
3849	</blockquote>
3850	<pre><code>bar
3851	</code></pre>
3852	````````````````````````````````
3853
3854
3855	```````````````````````````````` example
3856	> ```
3857	foo
3858	```
3859	.
3860	<blockquote>
3861	<pre><code></code></pre>
3862	</blockquote>
3863	<p>foo</p>
3864	<pre><code></code></pre>
3865	````````````````````````````````
3866
3867
3868	Note that in the following case, we have a [lazy
3869	continuation line]:
3870
3871	```````````````````````````````` example
3872	> foo
3873	- bar
3874	.
3875	<blockquote>
3876	<p>foo
3877	- bar</p>
3878	</blockquote>
3879	````````````````````````````````
3880
3881
3882	To see why, note that in
3883
3884	```markdown
3885	> foo
3886	> - bar
3887	```
3888
3889	the `- bar` is indented too far to start a list, and can't
3890	be an indented code block because indented code blocks cannot
3891	interrupt paragraphs, so it is [paragraph continuation text].
3892
3893	A block quote can be empty:
3894
3895	```````````````````````````````` example
3896	>
3897	.
3898	<blockquote>
3899	</blockquote>
3900	````````````````````````````````
3901
3902
3903	```````````````````````````````` example
3904	>
3905	>
3906	>
3907	.
3908	<blockquote>
3909	</blockquote>
3910	````````````````````````````````
3911
3912
3913	A block quote can have initial or final blank lines:
3914
3915	```````````````````````````````` example
3916	>
3917	> foo
3918	>
3919	.
3920	<blockquote>
3921	<p>foo</p>
3922	</blockquote>
3923	````````````````````````````````
3924
3925
3926	A blank line always separates block quotes:
3927
3928	```````````````````````````````` example
3929	> foo
3930
3931	> bar
3932	.
3933	<blockquote>
3934	<p>foo</p>
3935	</blockquote>
3936	<blockquote>
3937	<p>bar</p>
3938	</blockquote>
3939	````````````````````````````````
3940
3941
3942	(Most current Markdown implementations, including John Gruber's
3943	original `Markdown.pl`, will parse this example as a single block quote
3944	with two paragraphs. But it seems better to allow the author to decide
3945	whether two block quotes or one are wanted.)
3946
3947	Consecutiveness means that if we put these block quotes together,
3948	we get a single block quote:
3949
3950	```````````````````````````````` example
3951	> foo
3952	> bar
3953	.
3954	<blockquote>
3955	<p>foo
3956	bar</p>
3957	</blockquote>
3958	````````````````````````````````
3959
3960
3961	To get a block quote with two paragraphs, use:
3962
3963	```````````````````````````````` example
3964	> foo
3965	>
3966	> bar
3967	.
3968	<blockquote>
3969	<p>foo</p>
3970	<p>bar</p>
3971	</blockquote>
3972	````````````````````````````````
3973
3974
3975	Block quotes can interrupt paragraphs:
3976
3977	```````````````````````````````` example
3978	foo
3979	> bar
3980	.
3981	<p>foo</p>
3982	<blockquote>
3983	<p>bar</p>
3984	</blockquote>
3985	````````````````````````````````
3986
3987
3988	In general, blank lines are not needed before or after block
3989	quotes:
3990
3991	```````````````````````````````` example
3992	> aaa
3993	***
3994	> bbb
3995	.
3996	<blockquote>
3997	<p>aaa</p>
3998	</blockquote>
3999	<hr />
4000	<blockquote>
4001	<p>bbb</p>
4002	</blockquote>
4003	````````````````````````````````
4004
4005
4006	However, because of laziness, a blank line is needed between
4007	a block quote and a following paragraph:
4008
4009	```````````````````````````````` example
4010	> bar
4011	baz
4012	.
4013	<blockquote>
4014	<p>bar
4015	baz</p>
4016	</blockquote>
4017	````````````````````````````````
4018
4019
4020	```````````````````````````````` example
4021	> bar
4022
4023	baz
4024	.
4025	<blockquote>
4026	<p>bar</p>
4027	</blockquote>
4028	<p>baz</p>
4029	````````````````````````````````
4030
4031
4032	```````````````````````````````` example
4033	> bar
4034	>
4035	baz
4036	.
4037	<blockquote>
4038	<p>bar</p>
4039	</blockquote>
4040	<p>baz</p>
4041	````````````````````````````````
4042
4043
4044	It is a consequence of the Laziness rule that any number
4045	of initial `>`s may be omitted on a continuation line of a
4046	nested block quote:
4047
4048	```````````````````````````````` example
4049	> > > foo
4050	bar
4051	.
4052	<blockquote>
4053	<blockquote>
4054	<blockquote>
4055	<p>foo
4056	bar</p>
4057	</blockquote>
4058	</blockquote>
4059	</blockquote>
4060	````````````````````````````````
4061
4062
4063	```````````````````````````````` example
4064	>>> foo
4065	> bar
4066	>>baz
4067	.
4068	<blockquote>
4069	<blockquote>
4070	<blockquote>
4071	<p>foo
4072	bar
4073	baz</p>
4074	</blockquote>
4075	</blockquote>
4076	</blockquote>
4077	````````````````````````````````
4078
4079
4080	When including an indented code block in a block quote,
4081	remember that the [block quote marker] includes
4082	both the `>` and a following space of indentation. So *five spaces* are needed
4083	after the `>`:
4084
4085	```````````````````````````````` example
4086	> code
4087
4088	> not code
4089	.
4090	<blockquote>
4091	<pre><code>code
4092	</code></pre>
4093	</blockquote>
4094	<blockquote>
4095	<p>not code</p>
4096	</blockquote>
4097	````````````````````````````````
4098
4099
4100
4101	## List items
4102
4103	A [list marker](@) is a
4104	[bullet list marker] or an [ordered list marker].
4105
4106	A [bullet list marker](@)
4107	is a `-`, `+`, or `*` character.
4108
4109	An [ordered list marker](@)
4110	is a sequence of 1--9 arabic digits (`0-9`), followed by either a
4111	`.` character or a `)` character. (The reason for the length
4112	limit is that with 10 digits we start seeing integer overflows
4113	in some browsers.)
4114
4115	The following rules define [list items]:
4116
4117	1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of
4118	blocks *Bs* starting with a character other than a space or tab, and *M* is
4119	a list marker of width *W* followed by 1 ≤ *N* ≤ 4 spaces of indentation,
4120	then the result of prepending *M* and the following spaces to the first line
4121	of Ls*, and indenting subsequent lines of *Ls* by *W + N* spaces, is a
4122	list item with *Bs* as its contents. The type of the list item
4123	(bullet or ordered) is determined by the type of its list marker.
4124	If the list item is ordered, then it is also assigned a start
4125	number, based on the ordered list marker.
4126
4127	Exceptions:
4128
4129	1. When the first list item in a [list] interrupts
4130	a paragraph---that is, when it starts on a line that would
4131	otherwise count as [paragraph continuation text]---then (a)
4132	the lines *Ls* must not begin with a blank line, and (b) if
4133	the list item is ordered, the start number must be 1.
4134	2. If any line is a [thematic break][thematic breaks] then
4135	that line is not a list item.
4136
4137	For example, let *Ls* be the lines
4138
4139	```````````````````````````````` example
4140	A paragraph
4141	with two lines.
4142
4143	indented code
4144
4145	> A block quote.
4146	.
4147	<p>A paragraph
4148	with two lines.</p>
4149	<pre><code>indented code
4150	</code></pre>
4151	<blockquote>
4152	<p>A block quote.</p>
4153	</blockquote>
4154	````````````````````````````````
4155
4156
4157	And let *M* be the marker `1.`, and *N* = 2. Then rule #1 says
4158	that the following is an ordered list item with start number 1,
4159	and the same contents as *Ls*:
4160
4161	```````````````````````````````` example
4162	1. A paragraph
4163	with two lines.
4164
4165	indented code
4166
4167	> A block quote.
4168	.
4169	<ol>
4170	<li>
4171	<p>A paragraph
4172	with two lines.</p>
4173	<pre><code>indented code
4174	</code></pre>
4175	<blockquote>
4176	<p>A block quote.</p>
4177	</blockquote>
4178	</li>
4179	</ol>
4180	````````````````````````````````
4181
4182
4183	The most important thing to notice is that the position of
4184	the text after the list marker determines how much indentation
4185	is needed in subsequent blocks in the list item. If the list
4186	marker takes up two spaces of indentation, and there are three spaces between
4187	the list marker and the next character other than a space or tab, then blocks
4188	must be indented five spaces in order to fall under the list
4189	item.
4190
4191	Here are some examples showing how far content must be indented to be
4192	put under the list item:
4193
4194	```````````````````````````````` example
4195	- one
4196
4197	two
4198	.
4199	<ul>
4200	<li>one</li>
4201	</ul>
4202	<p>two</p>
4203	````````````````````````````````
4204
4205
4206	```````````````````````````````` example
4207	- one
4208
4209	two
4210	.
4211	<ul>
4212	<li>
4213	<p>one</p>
4214	<p>two</p>
4215	</li>
4216	</ul>
4217	````````````````````````````````
4218
4219
4220	```````````````````````````````` example
4221	- one
4222
4223	two
4224	.
4225	<ul>
4226	<li>one</li>
4227	</ul>
4228	<pre><code> two
4229	</code></pre>
4230	````````````````````````````````
4231
4232
4233	```````````````````````````````` example
4234	- one
4235
4236	two
4237	.
4238	<ul>
4239	<li>
4240	<p>one</p>
4241	<p>two</p>
4242	</li>
4243	</ul>
4244	````````````````````````````````
4245
4246
4247	It is tempting to think of this in terms of columns: the continuation
4248	blocks must be indented at least to the column of the first character other than
4249	a space or tab after the list marker. However, that is not quite right.
4250	The spaces of indentation after the list marker determine how much relative
4251	indentation is needed. Which column this indentation reaches will depend on
4252	how the list item is embedded in other constructions, as shown by
4253	this example:
4254
4255	```````````````````````````````` example
4256	> > 1. one
4257	>>
4258	>> two
4259	.
4260	<blockquote>
4261	<blockquote>
4262	<ol>
4263	<li>
4264	<p>one</p>
4265	<p>two</p>
4266	</li>
4267	</ol>
4268	</blockquote>
4269	</blockquote>
4270	````````````````````````````````
4271
4272
4273	Here `two` occurs in the same column as the list marker `1.`,
4274	but is actually contained in the list item, because there is
4275	sufficient indentation after the last containing blockquote marker.
4276
4277	The converse is also possible. In the following example, the word `two`
4278	occurs far to the right of the initial text of the list item, `one`, but
4279	it is not considered part of the list item, because it is not indented
4280	far enough past the blockquote marker:
4281
4282	```````````````````````````````` example
4283	>>- one
4284	>>
4285	> > two
4286	.
4287	<blockquote>
4288	<blockquote>
4289	<ul>
4290	<li>one</li>
4291	</ul>
4292	<p>two</p>
4293	</blockquote>
4294	</blockquote>
4295	````````````````````````````````
4296
4297
4298	Note that at least one space or tab is needed between the list marker and
4299	any following content, so these are not list items:
4300
4301	```````````````````````````````` example
4302	-one
4303
4304	2.two
4305	.
4306	<p>-one</p>
4307	<p>2.two</p>
4308	````````````````````````````````
4309
4310
4311	A list item may contain blocks that are separated by more than
4312	one blank line.
4313
4314	```````````````````````````````` example
4315	- foo
4316
4317
4318	bar
4319	.
4320	<ul>
4321	<li>
4322	<p>foo</p>
4323	<p>bar</p>
4324	</li>
4325	</ul>
4326	````````````````````````````````
4327
4328
4329	A list item may contain any kind of block:
4330
4331	```````````````````````````````` example
4332	1. foo
4333
4334	```
4335	bar
4336	```
4337
4338	baz
4339
4340	> bam
4341	.
4342	<ol>
4343	<li>
4344	<p>foo</p>
4345	<pre><code>bar
4346	</code></pre>
4347	<p>baz</p>
4348	<blockquote>
4349	<p>bam</p>
4350	</blockquote>
4351	</li>
4352	</ol>
4353	````````````````````````````````
4354
4355
4356	A list item that contains an indented code block will preserve
4357	empty lines within the code block verbatim.
4358
4359	```````````````````````````````` example
4360	- Foo
4361
4362	bar
4363
4364
4365	baz
4366	.
4367	<ul>
4368	<li>
4369	<p>Foo</p>
4370	<pre><code>bar
4371
4372
4373	baz
4374	</code></pre>
4375	</li>
4376	</ul>
4377	````````````````````````````````
4378
4379	Note that ordered list start numbers must be nine digits or less:
4380
4381	```````````````````````````````` example
4382	123456789. ok
4383	.
4384	<ol start="123456789">
4385	<li>ok</li>
4386	</ol>
4387	````````````````````````````````
4388
4389
4390	```````````````````````````````` example
4391	1234567890. not ok
4392	.
4393	<p>1234567890. not ok</p>
4394	````````````````````````````````
4395
4396
4397	A start number may begin with 0s:
4398
4399	```````````````````````````````` example
4400	0. ok
4401	.
4402	<ol start="0">
4403	<li>ok</li>
4404	</ol>
4405	````````````````````````````````
4406
4407
4408	```````````````````````````````` example
4409	003. ok
4410	.
4411	<ol start="3">
4412	<li>ok</li>
4413	</ol>
4414	````````````````````````````````
4415
4416
4417	A start number may not be negative:
4418
4419	```````````````````````````````` example
4420	-1. not ok
4421	.
4422	<p>-1. not ok</p>
4423	````````````````````````````````
4424
4425
4426
4427	2. **Item starting with indented code.** If a sequence of lines *Ls*
4428	constitute a sequence of blocks *Bs* starting with an indented code
4429	block, and *M* is a list marker of width *W* followed by
4430	one space of indentation, then the result of prepending *M* and the
4431	following space to the first line of *Ls*, and indenting subsequent lines
4432	of *Ls* by *W + 1* spaces, is a list item with *Bs* as its contents.
4433	If a line is empty, then it need not be indented. The type of the
4434	list item (bullet or ordered) is determined by the type of its list
4435	marker. If the list item is ordered, then it is also assigned a
4436	start number, based on the ordered list marker.
4437
4438	An indented code block will have to be preceded by four spaces of indentation
4439	beyond the edge of the region where text will be included in the list item.
4440	In the following case that is 6 spaces:
4441
4442	```````````````````````````````` example
4443	- foo
4444
4445	bar
4446	.
4447	<ul>
4448	<li>
4449	<p>foo</p>
4450	<pre><code>bar
4451	</code></pre>
4452	</li>
4453	</ul>
4454	````````````````````````````````
4455
4456
4457	And in this case it is 11 spaces:
4458
4459	```````````````````````````````` example
4460	10. foo
4461
4462	bar
4463	.
4464	<ol start="10">
4465	<li>
4466	<p>foo</p>
4467	<pre><code>bar
4468	</code></pre>
4469	</li>
4470	</ol>
4471	````````````````````````````````
4472
4473
4474	If the *first* block in the list item is an indented code block,
4475	then by rule #2, the contents must be preceded by *one* space of indentation
4476	after the list marker:
4477
4478	```````````````````````````````` example
4479	indented code
4480
4481	paragraph
4482
4483	more code
4484	.
4485	<pre><code>indented code
4486	</code></pre>
4487	<p>paragraph</p>
4488	<pre><code>more code
4489	</code></pre>
4490	````````````````````````````````
4491
4492
4493	```````````````````````````````` example
4494	1. indented code
4495
4496	paragraph
4497
4498	more code
4499	.
4500	<ol>
4501	<li>
4502	<pre><code>indented code
4503	</code></pre>
4504	<p>paragraph</p>
4505	<pre><code>more code
4506	</code></pre>
4507	</li>
4508	</ol>
4509	````````````````````````````````
4510
4511
4512	Note that an additional space of indentation is interpreted as space
4513	inside the code block:
4514
4515	```````````````````````````````` example
4516	1. indented code
4517
4518	paragraph
4519
4520	more code
4521	.
4522	<ol>
4523	<li>
4524	<pre><code> indented code
4525	</code></pre>
4526	<p>paragraph</p>
4527	<pre><code>more code
4528	</code></pre>
4529	</li>
4530	</ol>
4531	````````````````````````````````
4532
4533
4534	Note that rules #1 and #2 only apply to two cases: (a) cases
4535	in which the lines to be included in a list item begin with a
4536	characer other than a space or tab, and (b) cases in which
4537	they begin with an indented code
4538	block. In a case like the following, where the first block begins with
4539	three spaces of indentation, the rules do not allow us to form a list item by
4540	indenting the whole thing and prepending a list marker:
4541
4542	```````````````````````````````` example
4543	foo
4544
4545	bar
4546	.
4547	<p>foo</p>
4548	<p>bar</p>
4549	````````````````````````````````
4550
4551
4552	```````````````````````````````` example
4553	- foo
4554
4555	bar
4556	.
4557	<ul>
4558	<li>foo</li>
4559	</ul>
4560	<p>bar</p>
4561	````````````````````````````````
4562
4563
4564	This is not a significant restriction, because when a block is preceded by up to
4565	three spaces of indentation, the indentation can always be removed without
4566	a change in interpretation, allowing rule #1 to be applied. So, in
4567	the above case:
4568
4569	```````````````````````````````` example
4570	- foo
4571
4572	bar
4573	.
4574	<ul>
4575	<li>
4576	<p>foo</p>
4577	<p>bar</p>
4578	</li>
4579	</ul>
4580	````````````````````````````````
4581
4582
4583	3. **Item starting with a blank line.** If a sequence of lines *Ls*
4584	starting with a single [blank line] constitute a (possibly empty)
4585	sequence of blocks *Bs*, and *M* is a list marker of width *W*,
4586	then the result of prepending *M* to the first line of *Ls*, and
4587	preceding subsequent lines of *Ls* by *W + 1* spaces of indentation, is a
4588	list item with *Bs* as its contents.
4589	If a line is empty, then it need not be indented. The type of the
4590	list item (bullet or ordered) is determined by the type of its list
4591	marker. If the list item is ordered, then it is also assigned a
4592	start number, based on the ordered list marker.
4593
4594	Here are some list items that start with a blank line but are not empty:
4595
4596	```````````````````````````````` example
4597	-
4598	foo
4599	-
4600	```
4601	bar
4602	```
4603	-
4604	baz
4605	.
4606	<ul>
4607	<li>foo</li>
4608	<li>
4609	<pre><code>bar
4610	</code></pre>
4611	</li>
4612	<li>
4613	<pre><code>baz
4614	</code></pre>
4615	</li>
4616	</ul>
4617	````````````````````````````````
4618
4619	When the list item starts with a blank line, the number of spaces
4620	following the list marker doesn't change the required indentation:
4621
4622	```````````````````````````````` example
4623	-
4624	foo
4625	.
4626	<ul>
4627	<li>foo</li>
4628	</ul>
4629	````````````````````````````````
4630
4631
4632	A list item can begin with at most one blank line.
4633	In the following example, `foo` is not part of the list
4634	item:
4635
4636	```````````````````````````````` example
4637	-
4638
4639	foo
4640	.
4641	<ul>
4642	<li></li>
4643	</ul>
4644	<p>foo</p>
4645	````````````````````````````````
4646
4647
4648	Here is an empty bullet list item:
4649
4650	```````````````````````````````` example
4651	- foo
4652	-
4653	- bar
4654	.
4655	<ul>
4656	<li>foo</li>
4657	<li></li>
4658	<li>bar</li>
4659	</ul>
4660	````````````````````````````````
4661
4662
4663	It does not matter whether there are spaces or tabs following the [list marker]:
4664
4665	```````````````````````````````` example
4666	- foo
4667	-
4668	- bar
4669	.
4670	<ul>
4671	<li>foo</li>
4672	<li></li>
4673	<li>bar</li>
4674	</ul>
4675	````````````````````````````````
4676
4677
4678	Here is an empty ordered list item:
4679
4680	```````````````````````````````` example
4681	1. foo
4682	2.
4683	3. bar
4684	.
4685	<ol>
4686	<li>foo</li>
4687	<li></li>
4688	<li>bar</li>
4689	</ol>
4690	````````````````````````````````
4691
4692
4693	A list may start or end with an empty list item:
4694
4695	```````````````````````````````` example
4696	*
4697	.
4698	<ul>
4699	<li></li>
4700	</ul>
4701	````````````````````````````````
4702
4703	However, an empty list item cannot interrupt a paragraph:
4704
4705	```````````````````````````````` example
4706	foo
4707	*
4708
4709	foo
4710	1.
4711	.
4712	<p>foo
4713	*</p>
4714	<p>foo
4715	1.</p>
4716	````````````````````````````````
4717
4718
4719	4. **Indentation.** If a sequence of lines *Ls* constitutes a list item
4720	according to rule #1, #2, or #3, then the result of preceding each line
4721	of *Ls* by up to three spaces of indentation (the same for each line) also
4722	constitutes a list item with the same contents and attributes. If a line is
4723	empty, then it need not be indented.
4724
4725	Indented one space:
4726
4727	```````````````````````````````` example
4728	1. A paragraph
4729	with two lines.
4730
4731	indented code
4732
4733	> A block quote.
4734	.
4735	<ol>
4736	<li>
4737	<p>A paragraph
4738	with two lines.</p>
4739	<pre><code>indented code
4740	</code></pre>
4741	<blockquote>
4742	<p>A block quote.</p>
4743	</blockquote>
4744	</li>
4745	</ol>
4746	````````````````````````````````
4747
4748
4749	Indented two spaces:
4750
4751	```````````````````````````````` example
4752	1. A paragraph
4753	with two lines.
4754
4755	indented code
4756
4757	> A block quote.
4758	.
4759	<ol>
4760	<li>
4761	<p>A paragraph
4762	with two lines.</p>
4763	<pre><code>indented code
4764	</code></pre>
4765	<blockquote>
4766	<p>A block quote.</p>
4767	</blockquote>
4768	</li>
4769	</ol>
4770	````````````````````````````````
4771
4772
4773	Indented three spaces:
4774
4775	```````````````````````````````` example
4776	1. A paragraph
4777	with two lines.
4778
4779	indented code
4780
4781	> A block quote.
4782	.
4783	<ol>
4784	<li>
4785	<p>A paragraph
4786	with two lines.</p>
4787	<pre><code>indented code
4788	</code></pre>
4789	<blockquote>
4790	<p>A block quote.</p>
4791	</blockquote>
4792	</li>
4793	</ol>
4794	````````````````````````````````
4795
4796
4797	Four spaces indent gives a code block:
4798
4799	```````````````````````````````` example
4800	1. A paragraph
4801	with two lines.
4802
4803	indented code
4804
4805	> A block quote.
4806	.
4807	<pre><code>1. A paragraph
4808	with two lines.
4809
4810	indented code
4811
4812	&gt; A block quote.
4813	</code></pre>
4814	````````````````````````````````
4815
4816
4817
4818	5. **Laziness.** If a string of lines *Ls* constitute a [list
4819	item](#list-items) with contents *Bs*, then the result of deleting
4820	some or all of the indentation from one or more lines in which the
4821	next character other than a space or tab after the indentation is
4822	[paragraph continuation text] is a
4823	list item with the same contents and attributes. The unindented
4824	lines are called
4825	[lazy continuation line](@)s.
4826
4827	Here is an example with [lazy continuation lines]:
4828
4829	```````````````````````````````` example
4830	1. A paragraph
4831	with two lines.
4832
4833	indented code
4834
4835	> A block quote.
4836	.
4837	<ol>
4838	<li>
4839	<p>A paragraph
4840	with two lines.</p>
4841	<pre><code>indented code
4842	</code></pre>
4843	<blockquote>
4844	<p>A block quote.</p>
4845	</blockquote>
4846	</li>
4847	</ol>
4848	````````````````````````````````
4849
4850
4851	Indentation can be partially deleted:
4852
4853	```````````````````````````````` example
4854	1. A paragraph
4855	with two lines.
4856	.
4857	<ol>
4858	<li>A paragraph
4859	with two lines.</li>
4860	</ol>
4861	````````````````````````````````
4862
4863
4864	These examples show how laziness can work in nested structures:
4865
4866	```````````````````````````````` example
4867	> 1. > Blockquote
4868	continued here.
4869	.
4870	<blockquote>
4871	<ol>
4872	<li>
4873	<blockquote>
4874	<p>Blockquote
4875	continued here.</p>
4876	</blockquote>
4877	</li>
4878	</ol>
4879	</blockquote>
4880	````````````````````````````````
4881
4882
4883	```````````````````````````````` example
4884	> 1. > Blockquote
4885	> continued here.
4886	.
4887	<blockquote>
4888	<ol>
4889	<li>
4890	<blockquote>
4891	<p>Blockquote
4892	continued here.</p>
4893	</blockquote>
4894	</li>
4895	</ol>
4896	</blockquote>
4897	````````````````````````````````
4898
4899
4900
4901	6. **That's all.** Nothing that is not counted as a list item by rules
4902	#1--5 counts as a [list item](#list-items).
4903
4904	The rules for sublists follow from the general rules
4905	[above][List items]. A sublist must be indented the same number
4906	of spaces of indentation a paragraph would need to be in order to be included
4907	in the list item.
4908
4909	So, in this case we need two spaces indent:
4910
4911	```````````````````````````````` example
4912	- foo
4913	- bar
4914	- baz
4915	- boo
4916	.
4917	<ul>
4918	<li>foo
4919	<ul>
4920	<li>bar
4921	<ul>
4922	<li>baz
4923	<ul>
4924	<li>boo</li>
4925	</ul>
4926	</li>
4927	</ul>
4928	</li>
4929	</ul>
4930	</li>
4931	</ul>
4932	````````````````````````````````
4933
4934
4935	One is not enough:
4936
4937	```````````````````````````````` example
4938	- foo
4939	- bar
4940	- baz
4941	- boo
4942	.
4943	<ul>
4944	<li>foo</li>
4945	<li>bar</li>
4946	<li>baz</li>
4947	<li>boo</li>
4948	</ul>
4949	````````````````````````````````
4950
4951
4952	Here we need four, because the list marker is wider:
4953
4954	```````````````````````````````` example
4955	10) foo
4956	- bar
4957	.
4958	<ol start="10">
4959	<li>foo
4960	<ul>
4961	<li>bar</li>
4962	</ul>
4963	</li>
4964	</ol>
4965	````````````````````````````````
4966
4967
4968	Three is not enough:
4969
4970	```````````````````````````````` example
4971	10) foo
4972	- bar
4973	.
4974	<ol start="10">
4975	<li>foo</li>
4976	</ol>
4977	<ul>
4978	<li>bar</li>
4979	</ul>
4980	````````````````````````````````
4981
4982
4983	A list may be the first block in a list item:
4984
4985	```````````````````````````````` example
4986	- - foo
4987	.
4988	<ul>
4989	<li>
4990	<ul>
4991	<li>foo</li>
4992	</ul>
4993	</li>
4994	</ul>
4995	````````````````````````````````
4996
4997
4998	```````````````````````````````` example
4999	1. - 2. foo
5000	.
5001	<ol>
5002	<li>
5003	<ul>
5004	<li>
5005	<ol start="2">
5006	<li>foo</li>
5007	</ol>
5008	</li>
5009	</ul>
5010	</li>
5011	</ol>
5012	````````````````````````````````
5013
5014
5015	A list item can contain a heading:
5016
5017	```````````````````````````````` example
5018	- # Foo
5019	- Bar
5020	---
5021	baz
5022	.
5023	<ul>
5024	<li>
5025	<h1>Foo</h1>
5026	</li>
5027	<li>
5028	<h2>Bar</h2>
5029	baz</li>
5030	</ul>
5031	````````````````````````````````
5032
5033
5034	### Motivation
5035
5036	John Gruber's Markdown spec says the following about list items:
5037
5038	1. "List markers typically start at the left margin, but may be indented
5039	by up to three spaces. List markers must be followed by one or more
5040	spaces or a tab."
5041
5042	2. "To make lists look nice, you can wrap items with hanging indents....
5043	But if you don't want to, you don't have to."
5044
5045	3. "List items may consist of multiple paragraphs. Each subsequent
5046	paragraph in a list item must be indented by either 4 spaces or one
5047	tab."
5048
5049	4. "It looks nice if you indent every line of the subsequent paragraphs,
5050	but here again, Markdown will allow you to be lazy."
5051
5052	5. "To put a blockquote within a list item, the blockquote's `>`
5053	delimiters need to be indented."
5054
5055	6. "To put a code block within a list item, the code block needs to be
5056	indented twice — 8 spaces or two tabs."
5057
5058	These rules specify that a paragraph under a list item must be indented
5059	four spaces (presumably, from the left margin, rather than the start of
5060	the list marker, but this is not said), and that code under a list item
5061	must be indented eight spaces instead of the usual four. They also say
5062	that a block quote must be indented, but not by how much; however, the
5063	example given has four spaces indentation. Although nothing is said
5064	about other kinds of block-level content, it is certainly reasonable to
5065	infer that *all* block elements under a list item, including other
5066	lists, must be indented four spaces. This principle has been called the
5067	*four-space rule*.
5068
5069	The four-space rule is clear and principled, and if the reference
5070	implementation `Markdown.pl` had followed it, it probably would have
5071	become the standard. However, `Markdown.pl` allowed paragraphs and
5072	sublists to start with only two spaces indentation, at least on the
5073	outer level. Worse, its behavior was inconsistent: a sublist of an
5074	outer-level list needed two spaces indentation, but a sublist of this
5075	sublist needed three spaces. It is not surprising, then, that different
5076	implementations of Markdown have developed very different rules for
5077	determining what comes under a list item. (Pandoc and python-Markdown,
5078	for example, stuck with Gruber's syntax description and the four-space
5079	rule, while discount, redcarpet, marked, PHP Markdown, and others
5080	followed `Markdown.pl`'s behavior more closely.)
5081
5082	Unfortunately, given the divergences between implementations, there
5083	is no way to give a spec for list items that will be guaranteed not
5084	to break any existing documents. However, the spec given here should
5085	correctly handle lists formatted with either the four-space rule or
5086	the more forgiving `Markdown.pl` behavior, provided they are laid out
5087	in a way that is natural for a human to read.
5088
5089	The strategy here is to let the width and indentation of the list marker
5090	determine the indentation necessary for blocks to fall under the list
5091	item, rather than having a fixed and arbitrary number. The writer can
5092	think of the body of the list item as a unit which gets indented to the
5093	right enough to fit the list marker (and any indentation on the list
5094	marker). (The laziness rule, #5, then allows continuation lines to be
5095	unindented if needed.)
5096
5097	This rule is superior, we claim, to any rule requiring a fixed level of
5098	indentation from the margin. The four-space rule is clear but
5099	unnatural. It is quite unintuitive that
5100
5101	``` markdown
5102	- foo
5103
5104	bar
5105
5106	- baz
5107	```
5108
5109	should be parsed as two lists with an intervening paragraph,
5110
5111	``` html
5112	<ul>
5113	<li>foo</li>
5114	</ul>
5115	<p>bar</p>
5116	<ul>
5117	<li>baz</li>
5118	</ul>
5119	```
5120
5121	as the four-space rule demands, rather than a single list,
5122
5123	``` html
5124	<ul>
5125	<li>
5126	<p>foo</p>
5127	<p>bar</p>
5128	<ul>
5129	<li>baz</li>
5130	</ul>
5131	</li>
5132	</ul>
5133	```
5134
5135	The choice of four spaces is arbitrary. It can be learned, but it is
5136	not likely to be guessed, and it trips up beginners regularly.
5137
5138	Would it help to adopt a two-space rule? The problem is that such
5139	a rule, together with the rule allowing up to three spaces of indentation for
5140	the initial list marker, allows text that is indented *less than* the
5141	original list marker to be included in the list item. For example,
5142	`Markdown.pl` parses
5143
5144	``` markdown
5145	- one
5146
5147	two
5148	```
5149
5150	as a single list item, with `two` a continuation paragraph:
5151
5152	``` html
5153	<ul>
5154	<li>
5155	<p>one</p>
5156	<p>two</p>
5157	</li>
5158	</ul>
5159	```
5160
5161	and similarly
5162
5163	``` markdown
5164	> - one
5165	>
5166	> two
5167	```
5168
5169	as
5170
5171	``` html
5172	<blockquote>
5173	<ul>
5174	<li>
5175	<p>one</p>
5176	<p>two</p>
5177	</li>
5178	</ul>
5179	</blockquote>
5180	```
5181
5182	This is extremely unintuitive.
5183
5184	Rather than requiring a fixed indent from the margin, we could require
5185	a fixed indent (say, two spaces, or even one space) from the list marker (which
5186	may itself be indented). This proposal would remove the last anomaly
5187	discussed. Unlike the spec presented above, it would count the following
5188	as a list item with a subparagraph, even though the paragraph `bar`
5189	is not indented as far as the first paragraph `foo`:
5190
5191	``` markdown
5192	10. foo
5193
5194	bar
5195	```
5196
5197	Arguably this text does read like a list item with `bar` as a subparagraph,
5198	which may count in favor of the proposal. However, on this proposal indented
5199	code would have to be indented six spaces after the list marker. And this
5200	would break a lot of existing Markdown, which has the pattern:
5201
5202	``` markdown
5203	1. foo
5204
5205	indented code
5206	```
5207
5208	where the code is indented eight spaces. The spec above, by contrast, will
5209	parse this text as expected, since the code block's indentation is measured
5210	from the beginning of `foo`.
5211
5212	The one case that needs special treatment is a list item that *starts*
5213	with indented code. How much indentation is required in that case, since
5214	we don't have a "first paragraph" to measure from? Rule #2 simply stipulates
5215	that in such cases, we require one space indentation from the list marker
5216	(and then the normal four spaces for the indented code). This will match the
5217	four-space rule in cases where the list marker plus its initial indentation
5218	takes four spaces (a common case), but diverge in other cases.
5219
5220	## Lists
5221
5222	A [list](@) is a sequence of one or more
5223	list items [of the same type]. The list items
5224	may be separated by any number of blank lines.
5225
5226	Two list items are [of the same type](@)
5227	if they begin with a [list marker] of the same type.
5228	Two list markers are of the
5229	same type if (a) they are bullet list markers using the same character
5230	(`-`, `+`, or `*`) or (b) they are ordered list numbers with the same
5231	delimiter (either `.` or `)`).
5232
5233	A list is an [ordered list](@)
5234	if its constituent list items begin with
5235	[ordered list markers], and a
5236	[bullet list](@) if its constituent list
5237	items begin with [bullet list markers].
5238
5239	The [start number](@)
5240	of an [ordered list] is determined by the list number of
5241	its initial list item. The numbers of subsequent list items are
5242	disregarded.
5243
5244	A list is [loose](@) if any of its constituent
5245	list items are separated by blank lines, or if any of its constituent
5246	list items directly contain two block-level elements with a blank line
5247	between them. Otherwise a list is [tight](@).
5248	(The difference in HTML output is that paragraphs in a loose list are
5249	wrapped in `<p>` tags, while paragraphs in a tight list are not.)
5250
5251	Changing the bullet or ordered list delimiter starts a new list:
5252
5253	```````````````````````````````` example
5254	- foo
5255	- bar
5256	+ baz
5257	.
5258	<ul>
5259	<li>foo</li>
5260	<li>bar</li>
5261	</ul>
5262	<ul>
5263	<li>baz</li>
5264	</ul>
5265	````````````````````````````````
5266
5267
5268	```````````````````````````````` example
5269	1. foo
5270	2. bar
5271	3) baz
5272	.
5273	<ol>
5274	<li>foo</li>
5275	<li>bar</li>
5276	</ol>
5277	<ol start="3">
5278	<li>baz</li>
5279	</ol>
5280	````````````````````````````````
5281
5282
5283	In CommonMark, a list can interrupt a paragraph. That is,
5284	no blank line is needed to separate a paragraph from a following
5285	list:
5286
5287	```````````````````````````````` example
5288	Foo
5289	- bar
5290	- baz
5291	.
5292	<p>Foo</p>
5293	<ul>
5294	<li>bar</li>
5295	<li>baz</li>
5296	</ul>
5297	````````````````````````````````
5298
5299	`Markdown.pl` does not allow this, through fear of triggering a list
5300	via a numeral in a hard-wrapped line:
5301
5302	``` markdown
5303	The number of windows in my house is
5304	14. The number of doors is 6.
5305	```
5306
5307	Oddly, though, `Markdown.pl` *does* allow a blockquote to
5308	interrupt a paragraph, even though the same considerations might
5309	apply.
5310
5311	In CommonMark, we do allow lists to interrupt paragraphs, for
5312	two reasons. First, it is natural and not uncommon for people
5313	to start lists without blank lines:
5314
5315	``` markdown
5316	I need to buy
5317	- new shoes
5318	- a coat
5319	- a plane ticket
5320	```
5321
5322	Second, we are attracted to a
5323
5324	> [principle of uniformity](@):
5325	> if a chunk of text has a certain
5326	> meaning, it will continue to have the same meaning when put into a
5327	> container block (such as a list item or blockquote).
5328
5329	(Indeed, the spec for [list items] and [block quotes] presupposes
5330	this principle.) This principle implies that if
5331
5332	``` markdown
5333	* I need to buy
5334	- new shoes
5335	- a coat
5336	- a plane ticket
5337	```
5338
5339	is a list item containing a paragraph followed by a nested sublist,
5340	as all Markdown implementations agree it is (though the paragraph
5341	may be rendered without `<p>` tags, since the list is "tight"),
5342	then
5343
5344	``` markdown
5345	I need to buy
5346	- new shoes
5347	- a coat
5348	- a plane ticket
5349	```
5350
5351	by itself should be a paragraph followed by a nested sublist.
5352
5353	Since it is well established Markdown practice to allow lists to
5354	interrupt paragraphs inside list items, the [principle of
5355	uniformity] requires us to allow this outside list items as
5356	well. ([reStructuredText](http://docutils.sourceforge.net/rst.html)
5357	takes a different approach, requiring blank lines before lists
5358	even inside other list items.)
5359
5360	In order to solve of unwanted lists in paragraphs with
5361	hard-wrapped numerals, we allow only lists starting with `1` to
5362	interrupt paragraphs. Thus,
5363
5364	```````````````````````````````` example
5365	The number of windows in my house is
5366	14. The number of doors is 6.
5367	.
5368	<p>The number of windows in my house is
5369	14. The number of doors is 6.</p>
5370	````````````````````````````````
5371
5372	We may still get an unintended result in cases like
5373
5374	```````````````````````````````` example
5375	The number of windows in my house is
5376	1. The number of doors is 6.
5377	.
5378	<p>The number of windows in my house is</p>
5379	<ol>
5380	<li>The number of doors is 6.</li>
5381	</ol>
5382	````````````````````````````````
5383
5384	but this rule should prevent most spurious list captures.
5385
5386	There can be any number of blank lines between items:
5387
5388	```````````````````````````````` example
5389	- foo
5390
5391	- bar
5392
5393
5394	- baz
5395	.
5396	<ul>
5397	<li>
5398	<p>foo</p>
5399	</li>
5400	<li>
5401	<p>bar</p>
5402	</li>
5403	<li>
5404	<p>baz</p>
5405	</li>
5406	</ul>
5407	````````````````````````````````
5408
5409	```````````````````````````````` example
5410	- foo
5411	- bar
5412	- baz
5413
5414
5415	bim
5416	.
5417	<ul>
5418	<li>foo
5419	<ul>
5420	<li>bar
5421	<ul>
5422	<li>
5423	<p>baz</p>
5424	<p>bim</p>
5425	</li>
5426	</ul>
5427	</li>
5428	</ul>
5429	</li>
5430	</ul>
5431	````````````````````````````````
5432
5433
5434	To separate consecutive lists of the same type, or to separate a
5435	list from an indented code block that would otherwise be parsed
5436	as a subparagraph of the final list item, you can insert a blank HTML
5437	comment:
5438
5439	```````````````````````````````` example
5440	- foo
5441	- bar
5442
5443	<!-- -->
5444
5445	- baz
5446	- bim
5447	.
5448	<ul>
5449	<li>foo</li>
5450	<li>bar</li>
5451	</ul>
5452	<!-- -->
5453	<ul>
5454	<li>baz</li>
5455	<li>bim</li>
5456	</ul>
5457	````````````````````````````````
5458
5459
5460	```````````````````````````````` example
5461	- foo
5462
5463	notcode
5464
5465	- foo
5466
5467	<!-- -->
5468
5469	code
5470	.
5471	<ul>
5472	<li>
5473	<p>foo</p>
5474	<p>notcode</p>
5475	</li>
5476	<li>
5477	<p>foo</p>
5478	</li>
5479	</ul>
5480	<!-- -->
5481	<pre><code>code
5482	</code></pre>
5483	````````````````````````````````
5484
5485
5486	List items need not be indented to the same level. The following
5487	list items will be treated as items at the same list level,
5488	since none is indented enough to belong to the previous list
5489	item:
5490
5491	```````````````````````````````` example
5492	- a
5493	- b
5494	- c
5495	- d
5496	- e
5497	- f
5498	- g
5499	.
5500	<ul>
5501	<li>a</li>
5502	<li>b</li>
5503	<li>c</li>
5504	<li>d</li>
5505	<li>e</li>
5506	<li>f</li>
5507	<li>g</li>
5508	</ul>
5509	````````````````````````````````
5510
5511
5512	```````````````````````````````` example
5513	1. a
5514
5515	2. b
5516
5517	3. c
5518	.
5519	<ol>
5520	<li>
5521	<p>a</p>
5522	</li>
5523	<li>
5524	<p>b</p>
5525	</li>
5526	<li>
5527	<p>c</p>
5528	</li>
5529	</ol>
5530	````````````````````````````````
5531
5532	Note, however, that list items may not be preceded by more than
5533	three spaces of indentation. Here `- e` is treated as a paragraph continuation
5534	line, because it is indented more than three spaces:
5535
5536	```````````````````````````````` example
5537	- a
5538	- b
5539	- c
5540	- d
5541	- e
5542	.
5543	<ul>
5544	<li>a</li>
5545	<li>b</li>
5546	<li>c</li>
5547	<li>d
5548	- e</li>
5549	</ul>
5550	````````````````````````````````
5551
5552	And here, `3. c` is treated as in indented code block,
5553	because it is indented four spaces and preceded by a
5554	blank line.
5555
5556	```````````````````````````````` example
5557	1. a
5558
5559	2. b
5560
5561	3. c
5562	.
5563	<ol>
5564	<li>
5565	<p>a</p>
5566	</li>
5567	<li>
5568	<p>b</p>
5569	</li>
5570	</ol>
5571	<pre><code>3. c
5572	</code></pre>
5573	````````````````````````````````
5574
5575
5576	This is a loose list, because there is a blank line between
5577	two of the list items:
5578
5579	```````````````````````````````` example
5580	- a
5581	- b
5582
5583	- c
5584	.
5585	<ul>
5586	<li>
5587	<p>a</p>
5588	</li>
5589	<li>
5590	<p>b</p>
5591	</li>
5592	<li>
5593	<p>c</p>
5594	</li>
5595	</ul>
5596	````````````````````````````````
5597
5598
5599	So is this, with a empty second item:
5600
5601	```````````````````````````````` example
5602	* a
5603	*
5604
5605	* c
5606	.
5607	<ul>
5608	<li>
5609	<p>a</p>
5610	</li>
5611	<li></li>
5612	<li>
5613	<p>c</p>
5614	</li>
5615	</ul>
5616	````````````````````````````````
5617
5618
5619	These are loose lists, even though there are no blank lines between the items,
5620	because one of the items directly contains two block-level elements
5621	with a blank line between them:
5622
5623	```````````````````````````````` example
5624	- a
5625	- b
5626
5627	c
5628	- d
5629	.
5630	<ul>
5631	<li>
5632	<p>a</p>
5633	</li>
5634	<li>
5635	<p>b</p>
5636	<p>c</p>
5637	</li>
5638	<li>
5639	<p>d</p>
5640	</li>
5641	</ul>
5642	````````````````````````````````
5643
5644
5645	```````````````````````````````` example
5646	- a
5647	- b
5648
5649	[ref]: /url
5650	- d
5651	.
5652	<ul>
5653	<li>
5654	<p>a</p>
5655	</li>
5656	<li>
5657	<p>b</p>
5658	</li>
5659	<li>
5660	<p>d</p>
5661	</li>
5662	</ul>
5663	````````````````````````````````
5664
5665
5666	This is a tight list, because the blank lines are in a code block:
5667
5668	```````````````````````````````` example
5669	- a
5670	- ```
5671	b
5672
5673
5674	```
5675	- c
5676	.
5677	<ul>
5678	<li>a</li>
5679	<li>
5680	<pre><code>b
5681
5682
5683	</code></pre>
5684	</li>
5685	<li>c</li>
5686	</ul>
5687	````````````````````````````````
5688
5689
5690	This is a tight list, because the blank line is between two
5691	paragraphs of a sublist. So the sublist is loose while
5692	the outer list is tight:
5693
5694	```````````````````````````````` example
5695	- a
5696	- b
5697
5698	c
5699	- d
5700	.
5701	<ul>
5702	<li>a
5703	<ul>
5704	<li>
5705	<p>b</p>
5706	<p>c</p>
5707	</li>
5708	</ul>
5709	</li>
5710	<li>d</li>
5711	</ul>
5712	````````````````````````````````
5713
5714
5715	This is a tight list, because the blank line is inside the
5716	block quote:
5717
5718	```````````````````````````````` example
5719	* a
5720	> b
5721	>
5722	* c
5723	.
5724	<ul>
5725	<li>a
5726	<blockquote>
5727	<p>b</p>
5728	</blockquote>
5729	</li>
5730	<li>c</li>
5731	</ul>
5732	````````````````````````````````
5733
5734
5735	This list is tight, because the consecutive block elements
5736	are not separated by blank lines:
5737
5738	```````````````````````````````` example
5739	- a
5740	> b
5741	```
5742	c
5743	```
5744	- d
5745	.
5746	<ul>
5747	<li>a
5748	<blockquote>
5749	<p>b</p>
5750	</blockquote>
5751	<pre><code>c
5752	</code></pre>
5753	</li>
5754	<li>d</li>
5755	</ul>
5756	````````````````````````````````
5757
5758
5759	A single-paragraph list is tight:
5760
5761	```````````````````````````````` example
5762	- a
5763	.
5764	<ul>
5765	<li>a</li>
5766	</ul>
5767	````````````````````````````````
5768
5769
5770	```````````````````````````````` example
5771	- a
5772	- b
5773	.
5774	<ul>
5775	<li>a
5776	<ul>
5777	<li>b</li>
5778	</ul>
5779	</li>
5780	</ul>
5781	````````````````````````````````
5782
5783
5784	This list is loose, because of the blank line between the
5785	two block elements in the list item:
5786
5787	```````````````````````````````` example
5788	1. ```
5789	foo
5790	```
5791
5792	bar
5793	.
5794	<ol>
5795	<li>
5796	<pre><code>foo
5797	</code></pre>
5798	<p>bar</p>
5799	</li>
5800	</ol>
5801	````````````````````````````````
5802
5803
5804	Here the outer list is loose, the inner list tight:
5805
5806	```````````````````````````````` example
5807	* foo
5808	* bar
5809
5810	baz
5811	.
5812	<ul>
5813	<li>
5814	<p>foo</p>
5815	<ul>
5816	<li>bar</li>
5817	</ul>
5818	<p>baz</p>
5819	</li>
5820	</ul>
5821	````````````````````````````````
5822
5823
5824	```````````````````````````````` example
5825	- a
5826	- b
5827	- c
5828
5829	- d
5830	- e
5831	- f
5832	.
5833	<ul>
5834	<li>
5835	<p>a</p>
5836	<ul>
5837	<li>b</li>
5838	<li>c</li>
5839	</ul>
5840	</li>
5841	<li>
5842	<p>d</p>
5843	<ul>
5844	<li>e</li>
5845	<li>f</li>
5846	</ul>
5847	</li>
5848	</ul>
5849	````````````````````````````````
5850
5851
5852	# Inlines
5853
5854	Inlines are parsed sequentially from the beginning of the character
5855	stream to the end (left to right, in left-to-right languages).
5856	Thus, for example, in
5857
5858	```````````````````````````````` example
5859	`hi`lo`
5860	.
5861	<p><code>hi</code>lo`</p>
5862	````````````````````````````````
5863
5864	`hi` is parsed as code, leaving the backtick at the end as a literal
5865	backtick.
5866
5867
5868
5869	## Code spans
5870
5871	A [backtick string](@)
5872	is a string of one or more backtick characters (`` ` ``) that is neither
5873	preceded nor followed by a backtick.
5874
5875	A [code span](@) begins with a backtick string and ends with
5876	a backtick string of equal length. The contents of the code span are
5877	the characters between these two backtick strings, normalized in the
5878	following ways:
5879
5880	- First, [line endings] are converted to [spaces].
5881	- If the resulting string both begins *and* ends with a [space]
5882	character, but does not consist entirely of [space]
5883	characters, a single [space] character is removed from the
5884	front and back. This allows you to include code that begins
5885	or ends with backtick characters, which must be separated by
5886	whitespace from the opening or closing backtick strings.
5887
5888	This is a simple code span:
5889
5890	```````````````````````````````` example
5891	`foo`
5892	.
5893	<p><code>foo</code></p>
5894	````````````````````````````````
5895
5896
5897	Here two backticks are used, because the code contains a backtick.
5898	This example also illustrates stripping of a single leading and
5899	trailing space:
5900
5901	```````````````````````````````` example
5902	`` foo ` bar ``
5903	.
5904	<p><code>foo ` bar</code></p>
5905	````````````````````````````````
5906
5907
5908	This example shows the motivation for stripping leading and trailing
5909	spaces:
5910
5911	```````````````````````````````` example
5912	` `` `
5913	.
5914	<p><code>``</code></p>
5915	````````````````````````````````
5916
5917	Note that only *one* space is stripped:
5918
5919	```````````````````````````````` example
5920	` `` `
5921	.
5922	<p><code> `` </code></p>
5923	````````````````````````````````
5924
5925	The stripping only happens if the space is on both
5926	sides of the string:
5927
5928	```````````````````````````````` example
5929	` a`
5930	.
5931	<p><code> a</code></p>
5932	````````````````````````````````
5933
5934	Only [spaces], and not [unicode whitespace] in general, are
5935	stripped in this way:
5936
5937	```````````````````````````````` example
5938	` b `
5939	.
5940	<p><code> b </code></p>
5941	````````````````````````````````
5942
5943	No stripping occurs if the code span contains only spaces:
5944
5945	```````````````````````````````` example
5946	` `
5947	` `
5948	.
5949	<p><code> </code>
5950	<code> </code></p>
5951	````````````````````````````````
5952
5953
5954	[Line endings] are treated like spaces:
5955
5956	```````````````````````````````` example
5957	``
5958	foo
5959	bar
5960	baz
5961	``
5962	.
5963	<p><code>foo bar baz</code></p>
5964	````````````````````````````````
5965
5966	```````````````````````````````` example
5967	``
5968	foo
5969	``
5970	.
5971	<p><code>foo </code></p>
5972	````````````````````````````````
5973
5974
5975	Interior spaces are not collapsed:
5976
5977	```````````````````````````````` example
5978	`foo bar
5979	baz`
5980	.
5981	<p><code>foo bar baz</code></p>
5982	````````````````````````````````
5983
5984	Note that browsers will typically collapse consecutive spaces
5985	when rendering `<code>` elements, so it is recommended that
5986	the following CSS be used:
5987
5988	code{white-space: pre-wrap;}
5989
5990
5991	Note that backslash escapes do not work in code spans. All backslashes
5992	are treated literally:
5993
5994	```````````````````````````````` example
5995	`foo\`bar`
5996	.
5997	<p><code>foo\</code>bar`</p>
5998	````````````````````````````````
5999
6000
6001	Backslash escapes are never needed, because one can always choose a
6002	string of *n* backtick characters as delimiters, where the code does
6003	not contain any strings of exactly *n* backtick characters.
6004
6005	```````````````````````````````` example
6006	``foo`bar``
6007	.
6008	<p><code>foo`bar</code></p>
6009	````````````````````````````````
6010
6011	```````````````````````````````` example
6012	` foo `` bar `
6013	.
6014	<p><code>foo `` bar</code></p>
6015	````````````````````````````````
6016
6017
6018	Code span backticks have higher precedence than any other inline
6019	constructs except HTML tags and autolinks. Thus, for example, this is
6020	not parsed as emphasized text, since the second `*` is part of a code
6021	span:
6022
6023	```````````````````````````````` example
6024	*foo`*`
6025	.
6026	<p>*foo<code>*</code></p>
6027	````````````````````````````````
6028
6029
6030	And this is not parsed as a link:
6031
6032	```````````````````````````````` example
6033	[not a `link](/foo`)
6034	.
6035	<p>[not a <code>link](/foo</code>)</p>
6036	````````````````````````````````
6037
6038
6039	Code spans, HTML tags, and autolinks have the same precedence.
6040	Thus, this is code:
6041
6042	```````````````````````````````` example
6043	`<a href="`">`
6044	.
6045	<p><code>&lt;a href=&quot;</code>&quot;&gt;`</p>
6046	````````````````````````````````
6047
6048
6049	But this is an HTML tag:
6050
6051	```````````````````````````````` example
6052	<a href="`">`
6053	.
6054	<p><a href="`">`</p>
6055	````````````````````````````````
6056
6057
6058	And this is code:
6059
6060	```````````````````````````````` example
6061	`<http://foo.bar.`baz>`
6062	.
6063	<p><code>&lt;http://foo.bar.</code>baz&gt;`</p>
6064	````````````````````````````````
6065
6066
6067	But this is an autolink:
6068
6069	```````````````````````````````` example
6070	<http://foo.bar.`baz>`
6071	.
6072	<p><a href="http://foo.bar.%60baz">http://foo.bar.`baz</a>`</p>
6073	````````````````````````````````
6074
6075
6076	When a backtick string is not closed by a matching backtick string,
6077	we just have literal backticks:
6078
6079	```````````````````````````````` example
6080	```foo``
6081	.
6082	<p>```foo``</p>
6083	````````````````````````````````
6084
6085
6086	```````````````````````````````` example
6087	`foo
6088	.
6089	<p>`foo</p>
6090	````````````````````````````````
6091
6092	The following case also illustrates the need for opening and
6093	closing backtick strings to be equal in length:
6094
6095	```````````````````````````````` example
6096	`foo``bar``
6097	.
6098	<p>`foo<code>bar</code></p>
6099	````````````````````````````````
6100
6101
6102	## Emphasis and strong emphasis
6103
6104	John Gruber's original [Markdown syntax
6105	description](http://daringfireball.net/projects/markdown/syntax#em) says:
6106
6107	> Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
6108	> emphasis. Text wrapped with one `*` or `_` will be wrapped with an HTML
6109	> `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML `<strong>`
6110	> tag.
6111
6112	This is enough for most users, but these rules leave much undecided,
6113	especially when it comes to nested emphasis. The original
6114	`Markdown.pl` test suite makes it clear that triple `***` and
6115	`___` delimiters can be used for strong emphasis, and most
6116	implementations have also allowed the following patterns:
6117
6118	``` markdown
6119	***strong emph***
6120	***strong** in emph*
6121	***emph* in strong**
6122	**in strong *emph***
6123	*in emph **strong***
6124	```
6125
6126	The following patterns are less widely supported, but the intent
6127	is clear and they are useful (especially in contexts like bibliography
6128	entries):
6129
6130	``` markdown
6131	*emph *with emph* in it*
6132	**strong **with strong** in it**
6133	```
6134
6135	Many implementations have also restricted intraword emphasis to
6136	the `*` forms, to avoid unwanted emphasis in words containing
6137	internal underscores. (It is best practice to put these in code
6138	spans, but users often do not.)
6139
6140	``` markdown
6141	internal emphasis: foo*bar*baz
6142	no emphasis: foo_bar_baz
6143	```
6144
6145	The rules given below capture all of these patterns, while allowing
6146	for efficient parsing strategies that do not backtrack.
6147
6148	First, some definitions. A [delimiter run](@) is either
6149	a sequence of one or more `*` characters that is not preceded or
6150	followed by a non-backslash-escaped `*` character, or a sequence
6151	of one or more `_` characters that is not preceded or followed by
6152	a non-backslash-escaped `_` character.
6153
6154	A [left-flanking delimiter run](@) is
6155	a [delimiter run] that is (1) not followed by [Unicode whitespace],
6156	and either (2a) not followed by a [Unicode punctuation character], or
6157	(2b) followed by a [Unicode punctuation character] and
6158	preceded by [Unicode whitespace] or a [Unicode punctuation character].
6159	For purposes of this definition, the beginning and the end of
6160	the line count as Unicode whitespace.
6161
6162	A [right-flanking delimiter run](@) is
6163	a [delimiter run] that is (1) not preceded by [Unicode whitespace],
6164	and either (2a) not preceded by a [Unicode punctuation character], or
6165	(2b) preceded by a [Unicode punctuation character] and
6166	followed by [Unicode whitespace] or a [Unicode punctuation character].
6167	For purposes of this definition, the beginning and the end of
6168	the line count as Unicode whitespace.
6169
6170	Here are some examples of delimiter runs.
6171
6172	- left-flanking but not right-flanking:
6173
6174	```
6175	***abc
6176	_abc
6177	**"abc"
6178	_"abc"
6179	```
6180
6181	- right-flanking but not left-flanking:
6182
6183	```
6184	abc***
6185	abc_
6186	"abc"**
6187	"abc"_
6188	```
6189
6190	- Both left and right-flanking:
6191
6192	```
6193	abc***def
6194	"abc"_"def"
6195	```
6196
6197	- Neither left nor right-flanking:
6198
6199	```
6200	abc *** def
6201	a _ b
6202	```
6203
6204	(The idea of distinguishing left-flanking and right-flanking
6205	delimiter runs based on the character before and the character
6206	after comes from Roopesh Chander's
6207	[vfmd](http://www.vfmd.org/vfmd-spec/specification/#procedure-for-identifying-emphasis-tags).
6208	vfmd uses the terminology "emphasis indicator string" instead of "delimiter
6209	run," and its rules for distinguishing left- and right-flanking runs
6210	are a bit more complex than the ones given here.)
6211
6212	The following rules define emphasis and strong emphasis:
6213
6214	1. A single `*` character [can open emphasis](@)
6215	iff (if and only if) it is part of a [left-flanking delimiter run].
6216
6217	2. A single `_` character [can open emphasis] iff
6218	it is part of a [left-flanking delimiter run]
6219	and either (a) not part of a [right-flanking delimiter run]
6220	or (b) part of a [right-flanking delimiter run]
6221	preceded by a [Unicode punctuation character].
6222
6223	3. A single `*` character [can close emphasis](@)
6224	iff it is part of a [right-flanking delimiter run].
6225
6226	4. A single `_` character [can close emphasis] iff
6227	it is part of a [right-flanking delimiter run]
6228	and either (a) not part of a [left-flanking delimiter run]
6229	or (b) part of a [left-flanking delimiter run]
6230	followed by a [Unicode punctuation character].
6231
6232	5. A double `**` [can open strong emphasis](@)
6233	iff it is part of a [left-flanking delimiter run].
6234
6235	6. A double `__` [can open strong emphasis] iff
6236	it is part of a [left-flanking delimiter run]
6237	and either (a) not part of a [right-flanking delimiter run]
6238	or (b) part of a [right-flanking delimiter run]
6239	preceded by a [Unicode punctuation character].
6240
6241	7. A double `**` [can close strong emphasis](@)
6242	iff it is part of a [right-flanking delimiter run].
6243
6244	8. A double `__` [can close strong emphasis] iff
6245	it is part of a [right-flanking delimiter run]
6246	and either (a) not part of a [left-flanking delimiter run]
6247	or (b) part of a [left-flanking delimiter run]
6248	followed by a [Unicode punctuation character].
6249
6250	9. Emphasis begins with a delimiter that [can open emphasis] and ends
6251	with a delimiter that [can close emphasis], and that uses the same
6252	character (`_` or `*`) as the opening delimiter. The
6253	opening and closing delimiters must belong to separate
6254	[delimiter runs]. If one of the delimiters can both
6255	open and close emphasis, then the sum of the lengths of the
6256	delimiter runs containing the opening and closing delimiters
6257	must not be a multiple of 3 unless both lengths are
6258	multiples of 3.
6259
6260	10. Strong emphasis begins with a delimiter that
6261	[can open strong emphasis] and ends with a delimiter that
6262	[can close strong emphasis], and that uses the same character
6263	(`_` or `*`) as the opening delimiter. The
6264	opening and closing delimiters must belong to separate
6265	[delimiter runs]. If one of the delimiters can both open
6266	and close strong emphasis, then the sum of the lengths of
6267	the delimiter runs containing the opening and closing
6268	delimiters must not be a multiple of 3 unless both lengths
6269	are multiples of 3.
6270
6271	11. A literal `*` character cannot occur at the beginning or end of
6272	`*`-delimited emphasis or `**`-delimited strong emphasis, unless it
6273	is backslash-escaped.
6274
6275	12. A literal `_` character cannot occur at the beginning or end of
6276	`_`-delimited emphasis or `__`-delimited strong emphasis, unless it
6277	is backslash-escaped.
6278
6279	Where rules 1--12 above are compatible with multiple parsings,
6280	the following principles resolve ambiguity:
6281
6282	13. The number of nestings should be minimized. Thus, for example,
6283	an interpretation `<strong>...</strong>` is always preferred to
6284	`<em><em>...</em></em>`.
6285
6286	14. An interpretation `<em><strong>...</strong></em>` is always
6287	preferred to `<strong><em>...</em></strong>`.
6288
6289	15. When two potential emphasis or strong emphasis spans overlap,
6290	so that the second begins before the first ends and ends after
6291	the first ends, the first takes precedence. Thus, for example,
6292	`*foo _bar* baz_` is parsed as `<em>foo _bar</em> baz_` rather
6293	than `*foo <em>bar* baz</em>`.
6294
6295	16. When there are two potential emphasis or strong emphasis spans
6296	with the same closing delimiter, the shorter one (the one that
6297	opens later) takes precedence. Thus, for example,
6298	`**foo **bar baz**` is parsed as `**foo <strong>bar baz</strong>`
6299	rather than `<strong>foo **bar baz</strong>`.
6300
6301	17. Inline code spans, links, images, and HTML tags group more tightly
6302	than emphasis. So, when there is a choice between an interpretation
6303	that contains one of these elements and one that does not, the
6304	former always wins. Thus, for example, `*[foo*](bar)` is
6305	parsed as `*<a href="bar">foo*</a>` rather than as
6306	`<em>[foo</em>](bar)`.
6307
6308	These rules can be illustrated through a series of examples.
6309
6310	Rule 1:
6311
6312	```````````````````````````````` example
6313	*foo bar*
6314	.
6315	<p><em>foo bar</em></p>
6316	````````````````````````````````
6317
6318
6319	This is not emphasis, because the opening `*` is followed by
6320	whitespace, and hence not part of a [left-flanking delimiter run]:
6321
6322	```````````````````````````````` example
6323	a * foo bar*
6324	.
6325	<p>a * foo bar*</p>
6326	````````````````````````````````
6327
6328
6329	This is not emphasis, because the opening `*` is preceded
6330	by an alphanumeric and followed by punctuation, and hence
6331	not part of a [left-flanking delimiter run]:
6332
6333	```````````````````````````````` example
6334	a*"foo"*
6335	.
6336	<p>a*&quot;foo&quot;*</p>
6337	````````````````````````````````
6338
6339
6340	Unicode nonbreaking spaces count as whitespace, too:
6341
6342	```````````````````````````````` example
6343	* a *
6344	.
6345	<p>* a *</p>
6346	````````````````````````````````
6347
6348
6349	Intraword emphasis with `*` is permitted:
6350
6351	```````````````````````````````` example
6352	foo*bar*
6353	.
6354	<p>foo<em>bar</em></p>
6355	````````````````````````````````
6356
6357
6358	```````````````````````````````` example
6359	5*6*78
6360	.
6361	<p>5<em>6</em>78</p>
6362	````````````````````````````````
6363
6364
6365	Rule 2:
6366
6367	```````````````````````````````` example
6368	_foo bar_
6369	.
6370	<p><em>foo bar</em></p>
6371	````````````````````````````````
6372
6373
6374	This is not emphasis, because the opening `_` is followed by
6375	whitespace:
6376
6377	```````````````````````````````` example
6378	_ foo bar_
6379	.
6380	<p>_ foo bar_</p>
6381	````````````````````````````````
6382
6383
6384	This is not emphasis, because the opening `_` is preceded
6385	by an alphanumeric and followed by punctuation:
6386
6387	```````````````````````````````` example
6388	a_"foo"_
6389	.
6390	<p>a_&quot;foo&quot;_</p>
6391	````````````````````````````````
6392
6393
6394	Emphasis with `_` is not allowed inside words:
6395
6396	```````````````````````````````` example
6397	foo_bar_
6398	.
6399	<p>foo_bar_</p>
6400	````````````````````````````````
6401
6402
6403	```````````````````````````````` example
6404	5_6_78
6405	.
6406	<p>5_6_78</p>
6407	````````````````````````````````
6408
6409
6410	```````````````````````````````` example
6411	пристаням_стремятся_
6412	.
6413	<p>пристаням_стремятся_</p>
6414	````````````````````````````````
6415
6416
6417	Here `_` does not generate emphasis, because the first delimiter run
6418	is right-flanking and the second left-flanking:
6419
6420	```````````````````````````````` example
6421	aa_"bb"_cc
6422	.
6423	<p>aa_&quot;bb&quot;_cc</p>
6424	````````````````````````````````
6425
6426
6427	This is emphasis, even though the opening delimiter is
6428	both left- and right-flanking, because it is preceded by
6429	punctuation:
6430
6431	```````````````````````````````` example
6432	foo-_(bar)_
6433	.
6434	<p>foo-<em>(bar)</em></p>
6435	````````````````````````````````
6436
6437
6438	Rule 3:
6439
6440	This is not emphasis, because the closing delimiter does
6441	not match the opening delimiter:
6442
6443	```````````````````````````````` example
6444	_foo*
6445	.
6446	<p>_foo*</p>
6447	````````````````````````````````
6448
6449
6450	This is not emphasis, because the closing `*` is preceded by
6451	whitespace:
6452
6453	```````````````````````````````` example
6454	*foo bar *
6455	.
6456	<p>*foo bar *</p>
6457	````````````````````````````````
6458
6459
6460	A line ending also counts as whitespace:
6461
6462	```````````````````````````````` example
6463	*foo bar
6464	*
6465	.
6466	<p>*foo bar
6467	*</p>
6468	````````````````````````````````
6469
6470
6471	This is not emphasis, because the second `*` is
6472	preceded by punctuation and followed by an alphanumeric
6473	(hence it is not part of a [right-flanking delimiter run]:
6474
6475	```````````````````````````````` example
6476	*(*foo)
6477	.
6478	<p>*(*foo)</p>
6479	````````````````````````````````
6480
6481
6482	The point of this restriction is more easily appreciated
6483	with this example:
6484
6485	```````````````````````````````` example
6486	*(*foo*)*
6487	.
6488	<p><em>(<em>foo</em>)</em></p>
6489	````````````````````````````````
6490
6491
6492	Intraword emphasis with `*` is allowed:
6493
6494	```````````````````````````````` example
6495	*foo*bar
6496	.
6497	<p><em>foo</em>bar</p>
6498	````````````````````````````````
6499
6500
6501
6502	Rule 4:
6503
6504	This is not emphasis, because the closing `_` is preceded by
6505	whitespace:
6506
6507	```````````````````````````````` example
6508	_foo bar _
6509	.
6510	<p>_foo bar _</p>
6511	````````````````````````````````
6512
6513
6514	This is not emphasis, because the second `_` is
6515	preceded by punctuation and followed by an alphanumeric:
6516
6517	```````````````````````````````` example
6518	_(_foo)
6519	.
6520	<p>_(_foo)</p>
6521	````````````````````````````````
6522
6523
6524	This is emphasis within emphasis:
6525
6526	```````````````````````````````` example
6527	_(_foo_)_
6528	.
6529	<p><em>(<em>foo</em>)</em></p>
6530	````````````````````````````````
6531
6532
6533	Intraword emphasis is disallowed for `_`:
6534
6535	```````````````````````````````` example
6536	_foo_bar
6537	.
6538	<p>_foo_bar</p>
6539	````````````````````````````````
6540
6541
6542	```````````````````````````````` example
6543	_пристаням_стремятся
6544	.
6545	<p>_пристаням_стремятся</p>
6546	````````````````````````````````
6547
6548
6549	```````````````````````````````` example
6550	_foo_bar_baz_
6551	.
6552	<p><em>foo_bar_baz</em></p>
6553	````````````````````````````````
6554
6555
6556	This is emphasis, even though the closing delimiter is
6557	both left- and right-flanking, because it is followed by
6558	punctuation:
6559
6560	```````````````````````````````` example
6561	_(bar)_.
6562	.
6563	<p><em>(bar)</em>.</p>
6564	````````````````````````````````
6565
6566
6567	Rule 5:
6568
6569	```````````````````````````````` example
6570	**foo bar**
6571	.
6572	<p><strong>foo bar</strong></p>
6573	````````````````````````````````
6574
6575
6576	This is not strong emphasis, because the opening delimiter is
6577	followed by whitespace:
6578
6579	```````````````````````````````` example
6580	** foo bar**
6581	.
6582	<p>** foo bar**</p>
6583	````````````````````````````````
6584
6585
6586	This is not strong emphasis, because the opening `**` is preceded
6587	by an alphanumeric and followed by punctuation, and hence
6588	not part of a [left-flanking delimiter run]:
6589
6590	```````````````````````````````` example
6591	a**"foo"**
6592	.
6593	<p>a**&quot;foo&quot;**</p>
6594	````````````````````````````````
6595
6596
6597	Intraword strong emphasis with `**` is permitted:
6598
6599	```````````````````````````````` example
6600	foo**bar**
6601	.
6602	<p>foo<strong>bar</strong></p>
6603	````````````````````````````````
6604
6605
6606	Rule 6:
6607
6608	```````````````````````````````` example
6609	__foo bar__
6610	.
6611	<p><strong>foo bar</strong></p>
6612	````````````````````````````````
6613
6614
6615	This is not strong emphasis, because the opening delimiter is
6616	followed by whitespace:
6617
6618	```````````````````````````````` example
6619	__ foo bar__
6620	.
6621	<p>__ foo bar__</p>
6622	````````````````````````````````
6623
6624
6625	A line ending counts as whitespace:
6626	```````````````````````````````` example
6627	__
6628	foo bar__
6629	.
6630	<p>__
6631	foo bar__</p>
6632	````````````````````````````````
6633
6634
6635	This is not strong emphasis, because the opening `__` is preceded
6636	by an alphanumeric and followed by punctuation:
6637
6638	```````````````````````````````` example
6639	a__"foo"__
6640	.
6641	<p>a__&quot;foo&quot;__</p>
6642	````````````````````````````````
6643
6644
6645	Intraword strong emphasis is forbidden with `__`:
6646
6647	```````````````````````````````` example
6648	foo__bar__
6649	.
6650	<p>foo__bar__</p>
6651	````````````````````````````````
6652
6653
6654	```````````````````````````````` example
6655	5__6__78
6656	.
6657	<p>5__6__78</p>
6658	````````````````````````````````
6659
6660
6661	```````````````````````````````` example
6662	пристаням__стремятся__
6663	.
6664	<p>пристаням__стремятся__</p>
6665	````````````````````````````````
6666
6667
6668	```````````````````````````````` example
6669	__foo, __bar__, baz__
6670	.
6671	<p><strong>foo, <strong>bar</strong>, baz</strong></p>
6672	````````````````````````````````
6673
6674
6675	This is strong emphasis, even though the opening delimiter is
6676	both left- and right-flanking, because it is preceded by
6677	punctuation:
6678
6679	```````````````````````````````` example
6680	foo-__(bar)__
6681	.
6682	<p>foo-<strong>(bar)</strong></p>
6683	````````````````````````````````
6684
6685
6686
6687	Rule 7:
6688
6689	This is not strong emphasis, because the closing delimiter is preceded
6690	by whitespace:
6691
6692	```````````````````````````````` example
6693	**foo bar **
6694	.
6695	<p>**foo bar **</p>
6696	````````````````````````````````
6697
6698
6699	(Nor can it be interpreted as an emphasized `*foo bar *`, because of
6700	Rule 11.)
6701
6702	This is not strong emphasis, because the second `**` is
6703	preceded by punctuation and followed by an alphanumeric:
6704
6705	```````````````````````````````` example
6706	**(**foo)
6707	.
6708	<p>**(**foo)</p>
6709	````````````````````````````````
6710
6711
6712	The point of this restriction is more easily appreciated
6713	with these examples:
6714
6715	```````````````````````````````` example
6716	*(**foo**)*
6717	.
6718	<p><em>(<strong>foo</strong>)</em></p>
6719	````````````````````````````````
6720
6721
6722	```````````````````````````````` example
6723	**Gomphocarpus (*Gomphocarpus physocarpus*, syn.
6724	*Asclepias physocarpa*)**
6725	.
6726	<p><strong>Gomphocarpus (<em>Gomphocarpus physocarpus</em>, syn.
6727	<em>Asclepias physocarpa</em>)</strong></p>
6728	````````````````````````````````
6729
6730
6731	```````````````````````````````` example
6732	**foo "*bar*" foo**
6733	.
6734	<p><strong>foo &quot;<em>bar</em>&quot; foo</strong></p>
6735	````````````````````````````````
6736
6737
6738	Intraword emphasis:
6739
6740	```````````````````````````````` example
6741	**foo**bar
6742	.
6743	<p><strong>foo</strong>bar</p>
6744	````````````````````````````````
6745
6746
6747	Rule 8:
6748
6749	This is not strong emphasis, because the closing delimiter is
6750	preceded by whitespace:
6751
6752	```````````````````````````````` example
6753	__foo bar __
6754	.
6755	<p>__foo bar __</p>
6756	````````````````````````````````
6757
6758
6759	This is not strong emphasis, because the second `__` is
6760	preceded by punctuation and followed by an alphanumeric:
6761
6762	```````````````````````````````` example
6763	__(__foo)
6764	.
6765	<p>__(__foo)</p>
6766	````````````````````````````````
6767
6768
6769	The point of this restriction is more easily appreciated
6770	with this example:
6771
6772	```````````````````````````````` example
6773	_(__foo__)_
6774	.
6775	<p><em>(<strong>foo</strong>)</em></p>
6776	````````````````````````````````
6777
6778
6779	Intraword strong emphasis is forbidden with `__`:
6780
6781	```````````````````````````````` example
6782	__foo__bar
6783	.
6784	<p>__foo__bar</p>
6785	````````````````````````````````
6786
6787
6788	```````````````````````````````` example
6789	__пристаням__стремятся
6790	.
6791	<p>__пристаням__стремятся</p>
6792	````````````````````````````````
6793
6794
6795	```````````````````````````````` example
6796	__foo__bar__baz__
6797	.
6798	<p><strong>foo__bar__baz</strong></p>
6799	````````````````````````````````
6800
6801
6802	This is strong emphasis, even though the closing delimiter is
6803	both left- and right-flanking, because it is followed by
6804	punctuation:
6805
6806	```````````````````````````````` example
6807	__(bar)__.
6808	.
6809	<p><strong>(bar)</strong>.</p>
6810	````````````````````````````````
6811
6812
6813	Rule 9:
6814
6815	Any nonempty sequence of inline elements can be the contents of an
6816	emphasized span.
6817
6818	```````````````````````````````` example
6819	*foo [bar](/url)*
6820	.
6821	<p><em>foo <a href="/url">bar</a></em></p>
6822	````````````````````````````````
6823
6824
6825	```````````````````````````````` example
6826	*foo
6827	bar*
6828	.
6829	<p><em>foo
6830	bar</em></p>
6831	````````````````````````````````
6832
6833
6834	In particular, emphasis and strong emphasis can be nested
6835	inside emphasis:
6836
6837	```````````````````````````````` example
6838	_foo __bar__ baz_
6839	.
6840	<p><em>foo <strong>bar</strong> baz</em></p>
6841	````````````````````````````````
6842
6843
6844	```````````````````````````````` example
6845	_foo _bar_ baz_
6846	.
6847	<p><em>foo <em>bar</em> baz</em></p>
6848	````````````````````````````````
6849
6850
6851	```````````````````````````````` example
6852	__foo_ bar_
6853	.
6854	<p><em><em>foo</em> bar</em></p>
6855	````````````````````````````````
6856
6857
6858	```````````````````````````````` example
6859	*foo *bar**
6860	.
6861	<p><em>foo <em>bar</em></em></p>
6862	````````````````````````````````
6863
6864
6865	```````````````````````````````` example
6866	*foo **bar** baz*
6867	.
6868	<p><em>foo <strong>bar</strong> baz</em></p>
6869	````````````````````````````````
6870
6871	```````````````````````````````` example
6872	*foo**bar**baz*
6873	.
6874	<p><em>foo<strong>bar</strong>baz</em></p>
6875	````````````````````````````````
6876
6877	Note that in the preceding case, the interpretation
6878
6879	``` markdown
6880	<p><em>foo</em><em>bar<em></em>baz</em></p>
6881	```
6882
6883
6884	is precluded by the condition that a delimiter that
6885	can both open and close (like the `*` after `foo`)
6886	cannot form emphasis if the sum of the lengths of
6887	the delimiter runs containing the opening and
6888	closing delimiters is a multiple of 3 unless
6889	both lengths are multiples of 3.
6890
6891
6892	For the same reason, we don't get two consecutive
6893	emphasis sections in this example:
6894
6895	```````````````````````````````` example
6896	*foo**bar*
6897	.
6898	<p><em>foo**bar</em></p>
6899	````````````````````````````````
6900
6901
6902	The same condition ensures that the following
6903	cases are all strong emphasis nested inside
6904	emphasis, even when the interior whitespace is
6905	omitted:
6906
6907
6908	```````````````````````````````` example
6909	***foo** bar*
6910	.
6911	<p><em><strong>foo</strong> bar</em></p>
6912	````````````````````````````````
6913
6914
6915	```````````````````````````````` example
6916	*foo **bar***
6917	.
6918	<p><em>foo <strong>bar</strong></em></p>
6919	````````````````````````````````
6920
6921
6922	```````````````````````````````` example
6923	*foo**bar***
6924	.
6925	<p><em>foo<strong>bar</strong></em></p>
6926	````````````````````````````````
6927
6928
6929	When the lengths of the interior closing and opening
6930	delimiter runs are *both* multiples of 3, though,
6931	they can match to create emphasis:
6932
6933	```````````````````````````````` example
6934	foo***bar***baz
6935	.
6936	<p>foo<em><strong>bar</strong></em>baz</p>
6937	````````````````````````````````
6938
6939	```````````````````````````````` example
6940	foo******bar*********baz
6941	.
6942	<p>foo<strong><strong><strong>bar</strong></strong></strong>***baz</p>
6943	````````````````````````````````
6944
6945
6946	Indefinite levels of nesting are possible:
6947
6948	```````````````````````````````` example
6949	*foo **bar *baz* bim** bop*
6950	.
6951	<p><em>foo <strong>bar <em>baz</em> bim</strong> bop</em></p>
6952	````````````````````````````````
6953
6954
6955	```````````````````````````````` example
6956	*foo [*bar*](/url)*
6957	.
6958	<p><em>foo <a href="/url"><em>bar</em></a></em></p>
6959	````````````````````````````````
6960
6961
6962	There can be no empty emphasis or strong emphasis:
6963
6964	```````````````````````````````` example
6965	** is not an empty emphasis
6966	.
6967	<p>** is not an empty emphasis</p>
6968	````````````````````````````````
6969
6970
6971	```````````````````````````````` example
6972	**** is not an empty strong emphasis
6973	.
6974	<p>**** is not an empty strong emphasis</p>
6975	````````````````````````````````
6976
6977
6978
6979	Rule 10:
6980
6981	Any nonempty sequence of inline elements can be the contents of an
6982	strongly emphasized span.
6983
6984	```````````````````````````````` example
6985	**foo [bar](/url)**
6986	.
6987	<p><strong>foo <a href="/url">bar</a></strong></p>
6988	````````````````````````````````
6989
6990
6991	```````````````````````````````` example
6992	**foo
6993	bar**
6994	.
6995	<p><strong>foo
6996	bar</strong></p>
6997	````````````````````````````````
6998
6999
7000	In particular, emphasis and strong emphasis can be nested
7001	inside strong emphasis:
7002
7003	```````````````````````````````` example
7004	__foo _bar_ baz__
7005	.
7006	<p><strong>foo <em>bar</em> baz</strong></p>
7007	````````````````````````````````
7008
7009
7010	```````````````````````````````` example
7011	__foo __bar__ baz__
7012	.
7013	<p><strong>foo <strong>bar</strong> baz</strong></p>
7014	````````````````````````````````
7015
7016
7017	```````````````````````````````` example
7018	____foo__ bar__
7019	.
7020	<p><strong><strong>foo</strong> bar</strong></p>
7021	````````````````````````````````
7022
7023
7024	```````````````````````````````` example
7025	**foo **bar****
7026	.
7027	<p><strong>foo <strong>bar</strong></strong></p>
7028	````````````````````````````````
7029
7030
7031	```````````````````````````````` example
7032	**foo *bar* baz**
7033	.
7034	<p><strong>foo <em>bar</em> baz</strong></p>
7035	````````````````````````````````
7036
7037
7038	```````````````````````````````` example
7039	**foo*bar*baz**
7040	.
7041	<p><strong>foo<em>bar</em>baz</strong></p>
7042	````````````````````````````````
7043
7044
7045	```````````````````````````````` example
7046	***foo* bar**
7047	.
7048	<p><strong><em>foo</em> bar</strong></p>
7049	````````````````````````````````
7050
7051
7052	```````````````````````````````` example
7053	**foo *bar***
7054	.
7055	<p><strong>foo <em>bar</em></strong></p>
7056	````````````````````````````````
7057
7058
7059	Indefinite levels of nesting are possible:
7060
7061	```````````````````````````````` example
7062	**foo *bar **baz**
7063	bim* bop**
7064	.
7065	<p><strong>foo <em>bar <strong>baz</strong>
7066	bim</em> bop</strong></p>
7067	````````````````````````````````
7068
7069
7070	```````````````````````````````` example
7071	**foo [*bar*](/url)**
7072	.
7073	<p><strong>foo <a href="/url"><em>bar</em></a></strong></p>
7074	````````````````````````````````
7075
7076
7077	There can be no empty emphasis or strong emphasis:
7078
7079	```````````````````````````````` example
7080	__ is not an empty emphasis
7081	.
7082	<p>__ is not an empty emphasis</p>
7083	````````````````````````````````
7084
7085
7086	```````````````````````````````` example
7087	____ is not an empty strong emphasis
7088	.
7089	<p>____ is not an empty strong emphasis</p>
7090	````````````````````````````````
7091
7092
7093
7094	Rule 11:
7095
7096	```````````````````````````````` example
7097	foo ***
7098	.
7099	<p>foo ***</p>
7100	````````````````````````````````
7101
7102
7103	```````````````````````````````` example
7104	foo *\**
7105	.
7106	<p>foo <em>*</em></p>
7107	````````````````````````````````
7108
7109
7110	```````````````````````````````` example
7111	foo *_*
7112	.
7113	<p>foo <em>_</em></p>
7114	````````````````````````````````
7115
7116
7117	```````````````````````````````` example
7118	foo *****
7119	.
7120	<p>foo *****</p>
7121	````````````````````````````````
7122
7123
7124	```````````````````````````````` example
7125	foo **\***
7126	.
7127	<p>foo <strong>*</strong></p>
7128	````````````````````````````````
7129
7130
7131	```````````````````````````````` example
7132	foo **_**
7133	.
7134	<p>foo <strong>_</strong></p>
7135	````````````````````````````````
7136
7137
7138	Note that when delimiters do not match evenly, Rule 11 determines
7139	that the excess literal `*` characters will appear outside of the
7140	emphasis, rather than inside it:
7141
7142	```````````````````````````````` example
7143	**foo*
7144	.
7145	<p>*<em>foo</em></p>
7146	````````````````````````````````
7147
7148
7149	```````````````````````````````` example
7150	*foo**
7151	.
7152	<p><em>foo</em>*</p>
7153	````````````````````````````````
7154
7155
7156	```````````````````````````````` example
7157	***foo**
7158	.
7159	<p>*<strong>foo</strong></p>
7160	````````````````````````````````
7161
7162
7163	```````````````````````````````` example
7164	****foo*
7165	.
7166	<p>***<em>foo</em></p>
7167	````````````````````````````````
7168
7169
7170	```````````````````````````````` example
7171	**foo***
7172	.
7173	<p><strong>foo</strong>*</p>
7174	````````````````````````````````
7175
7176
7177	```````````````````````````````` example
7178	*foo****
7179	.
7180	<p><em>foo</em>***</p>
7181	````````````````````````````````
7182
7183
7184
7185	Rule 12:
7186
7187	```````````````````````````````` example
7188	foo ___
7189	.
7190	<p>foo ___</p>
7191	````````````````````````````````
7192
7193
7194	```````````````````````````````` example
7195	foo _\__
7196	.
7197	<p>foo <em>_</em></p>
7198	````````````````````````````````
7199
7200
7201	```````````````````````````````` example
7202	foo _*_
7203	.
7204	<p>foo <em>*</em></p>
7205	````````````````````````````````
7206
7207
7208	```````````````````````````````` example
7209	foo _____
7210	.
7211	<p>foo _____</p>
7212	````````````````````````````````
7213
7214
7215	```````````````````````````````` example
7216	foo __\___
7217	.
7218	<p>foo <strong>_</strong></p>
7219	````````````````````````````````
7220
7221
7222	```````````````````````````````` example
7223	foo __*__
7224	.
7225	<p>foo <strong>*</strong></p>
7226	````````````````````````````````
7227
7228
7229	```````````````````````````````` example
7230	__foo_
7231	.
7232	<p>_<em>foo</em></p>
7233	````````````````````````````````
7234
7235
7236	Note that when delimiters do not match evenly, Rule 12 determines
7237	that the excess literal `_` characters will appear outside of the
7238	emphasis, rather than inside it:
7239
7240	```````````````````````````````` example
7241	_foo__
7242	.
7243	<p><em>foo</em>_</p>
7244	````````````````````````````````
7245
7246
7247	```````````````````````````````` example
7248	___foo__
7249	.
7250	<p>_<strong>foo</strong></p>
7251	````````````````````````````````
7252
7253
7254	```````````````````````````````` example
7255	____foo_
7256	.
7257	<p>___<em>foo</em></p>
7258	````````````````````````````````
7259
7260
7261	```````````````````````````````` example
7262	__foo___
7263	.
7264	<p><strong>foo</strong>_</p>
7265	````````````````````````````````
7266
7267
7268	```````````````````````````````` example
7269	_foo____
7270	.
7271	<p><em>foo</em>___</p>
7272	````````````````````````````````
7273
7274
7275	Rule 13 implies that if you want emphasis nested directly inside
7276	emphasis, you must use different delimiters:
7277
7278	```````````````````````````````` example
7279	**foo**
7280	.
7281	<p><strong>foo</strong></p>
7282	````````````````````````````````
7283
7284
7285	```````````````````````````````` example
7286	*_foo_*
7287	.
7288	<p><em><em>foo</em></em></p>
7289	````````````````````````````````
7290
7291
7292	```````````````````````````````` example
7293	__foo__
7294	.
7295	<p><strong>foo</strong></p>
7296	````````````````````````````````
7297
7298
7299	```````````````````````````````` example
7300	_*foo*_
7301	.
7302	<p><em><em>foo</em></em></p>
7303	````````````````````````````````
7304
7305
7306	However, strong emphasis within strong emphasis is possible without
7307	switching delimiters:
7308
7309	```````````````````````````````` example
7310	****foo****
7311	.
7312	<p><strong><strong>foo</strong></strong></p>
7313	````````````````````````````````
7314
7315
7316	```````````````````````````````` example
7317	____foo____
7318	.
7319	<p><strong><strong>foo</strong></strong></p>
7320	````````````````````````````````
7321
7322
7323
7324	Rule 13 can be applied to arbitrarily long sequences of
7325	delimiters:
7326
7327	```````````````````````````````` example
7328	******foo******
7329	.
7330	<p><strong><strong><strong>foo</strong></strong></strong></p>
7331	````````````````````````````````
7332
7333
7334	Rule 14:
7335
7336	```````````````````````````````` example
7337	***foo***
7338	.
7339	<p><em><strong>foo</strong></em></p>
7340	````````````````````````````````
7341
7342
7343	```````````````````````````````` example
7344	_____foo_____
7345	.
7346	<p><em><strong><strong>foo</strong></strong></em></p>
7347	````````````````````````````````
7348
7349
7350	Rule 15:
7351
7352	```````````````````````````````` example
7353	*foo _bar* baz_
7354	.
7355	<p><em>foo _bar</em> baz_</p>
7356	````````````````````````````````
7357
7358
7359	```````````````````````````````` example
7360	*foo __bar *baz bim__ bam*
7361	.
7362	<p><em>foo <strong>bar *baz bim</strong> bam</em></p>
7363	````````````````````````````````
7364
7365
7366	Rule 16:
7367
7368	```````````````````````````````` example
7369	**foo **bar baz**
7370	.
7371	<p>**foo <strong>bar baz</strong></p>
7372	````````````````````````````````
7373
7374
7375	```````````````````````````````` example
7376	*foo *bar baz*
7377	.
7378	<p>*foo <em>bar baz</em></p>
7379	````````````````````````````````
7380
7381
7382	Rule 17:
7383
7384	```````````````````````````````` example
7385	*[bar*](/url)
7386	.
7387	<p>*<a href="/url">bar*</a></p>
7388	````````````````````````````````
7389
7390
7391	```````````````````````````````` example
7392	_foo [bar_](/url)
7393	.
7394	<p>_foo <a href="/url">bar_</a></p>
7395	````````````````````````````````
7396
7397
7398	```````````````````````````````` example
7399	*<img src="foo" title="*"/>
7400	.
7401	<p>*<img src="foo" title="*"/></p>
7402	````````````````````````````````
7403
7404
7405	```````````````````````````````` example
7406	**<a href="**">
7407	.
7408	<p>**<a href="**"></p>
7409	````````````````````````````````
7410
7411
7412	```````````````````````````````` example
7413	__<a href="__">
7414	.
7415	<p>__<a href="__"></p>
7416	````````````````````````````````
7417
7418
7419	```````````````````````````````` example
7420	*a `*`*
7421	.
7422	<p><em>a <code>*</code></em></p>
7423	````````````````````````````````
7424
7425
7426	```````````````````````````````` example
7427	_a `_`_
7428	.
7429	<p><em>a <code>_</code></em></p>
7430	````````````````````````````````
7431
7432
7433	```````````````````````````````` example
7434	**a<http://foo.bar/?q=**>
7435	.
7436	<p>**a<a href="http://foo.bar/?q=**">http://foo.bar/?q=**</a></p>
7437	````````````````````````````````
7438
7439
7440	```````````````````````````````` example
7441	__a<http://foo.bar/?q=__>
7442	.
7443	<p>__a<a href="http://foo.bar/?q=__">http://foo.bar/?q=__</a></p>
7444	````````````````````````````````
7445
7446
7447
7448	## Links
7449
7450	A link contains [link text] (the visible text), a [link destination]
7451	(the URI that is the link destination), and optionally a [link title].
7452	There are two basic kinds of links in Markdown. In [inline links] the
7453	destination and title are given immediately after the link text. In
7454	[reference links] the destination and title are defined elsewhere in
7455	the document.
7456
7457	A [link text](@) consists of a sequence of zero or more
7458	inline elements enclosed by square brackets (`[` and `]`). The
7459	following rules apply:
7460
7461	- Links may not contain other links, at any level of nesting. If
7462	multiple otherwise valid link definitions appear nested inside each
7463	other, the inner-most definition is used.
7464
7465	- Brackets are allowed in the [link text] only if (a) they
7466	are backslash-escaped or (b) they appear as a matched pair of brackets,
7467	with an open bracket `[`, a sequence of zero or more inlines, and
7468	a close bracket `]`.
7469
7470	- Backtick [code spans], [autolinks], and raw [HTML tags] bind more tightly
7471	than the brackets in link text. Thus, for example,
7472	`` [foo`]` `` could not be a link text, since the second `]`
7473	is part of a code span.
7474
7475	- The brackets in link text bind more tightly than markers for
7476	[emphasis and strong emphasis]. Thus, for example, `*[foo*](url)` is a link.
7477
7478	A [link destination](@) consists of either
7479
7480	- a sequence of zero or more characters between an opening `<` and a
7481	closing `>` that contains no line endings or unescaped
7482	`<` or `>` characters, or
7483
7484	- a nonempty sequence of characters that does not start with `<`,
7485	does not include [ASCII control characters][ASCII control character]
7486	or [space] character, and includes parentheses only if (a) they are
7487	backslash-escaped or (b) they are part of a balanced pair of
7488	unescaped parentheses.
7489	(Implementations may impose limits on parentheses nesting to
7490	avoid performance issues, but at least three levels of nesting
7491	should be supported.)
7492
7493	A [link title](@) consists of either
7494
7495	- a sequence of zero or more characters between straight double-quote
7496	characters (`"`), including a `"` character only if it is
7497	backslash-escaped, or
7498
7499	- a sequence of zero or more characters between straight single-quote
7500	characters (`'`), including a `'` character only if it is
7501	backslash-escaped, or
7502
7503	- a sequence of zero or more characters between matching parentheses
7504	(`(...)`), including a `(` or `)` character only if it is
7505	backslash-escaped.
7506
7507	Although [link titles] may span multiple lines, they may not contain
7508	a [blank line].
7509
7510	An [inline link](@) consists of a [link text] followed immediately
7511	by a left parenthesis `(`, an optional [link destination], an optional
7512	[link title], and a right parenthesis `)`.
7513	These four components may be separated by spaces, tabs, and up to one line
7514	ending.
7515	If both [link destination] and [link title] are present, they *must* be
7516	separated by spaces, tabs, and up to one line ending.
7517
7518	The link's text consists of the inlines contained
7519	in the [link text] (excluding the enclosing square brackets).
7520	The link's URI consists of the link destination, excluding enclosing
7521	`<...>` if present, with backslash-escapes in effect as described
7522	above. The link's title consists of the link title, excluding its
7523	enclosing delimiters, with backslash-escapes in effect as described
7524	above.
7525
7526	Here is a simple inline link:
7527
7528	```````````````````````````````` example
7529	[link](/uri "title")
7530	.
7531	<p><a href="/uri" title="title">link</a></p>
7532	````````````````````````````````
7533
7534
7535	The title, the link text and even
7536	the destination may be omitted:
7537
7538	```````````````````````````````` example
7539	[link](/uri)
7540	.
7541	<p><a href="/uri">link</a></p>
7542	````````````````````````````````
7543
7544	```````````````````````````````` example
7545	[](./target.md)
7546	.
7547	<p><a href="./target.md"></a></p>
7548	````````````````````````````````
7549
7550
7551	```````````````````````````````` example
7552	[link]()
7553	.
7554	<p><a href="">link</a></p>
7555	````````````````````````````````
7556
7557
7558	```````````````````````````````` example
7559	[link](<>)
7560	.
7561	<p><a href="">link</a></p>
7562	````````````````````````````````
7563
7564
7565	```````````````````````````````` example
7566	[]()
7567	.
7568	<p><a href=""></a></p>
7569	````````````````````````````````
7570
7571	The destination can only contain spaces if it is
7572	enclosed in pointy brackets:
7573
7574	```````````````````````````````` example
7575	[link](/my uri)
7576	.
7577	<p>[link](/my uri)</p>
7578	````````````````````````````````
7579
7580	```````````````````````````````` example
7581	[link](</my uri>)
7582	.
7583	<p><a href="/my%20uri">link</a></p>
7584	````````````````````````````````
7585
7586	The destination cannot contain line endings,
7587	even if enclosed in pointy brackets:
7588
7589	```````````````````````````````` example
7590	[link](foo
7591	bar)
7592	.
7593	<p>[link](foo
7594	bar)</p>
7595	````````````````````````````````
7596
7597	```````````````````````````````` example
7598	[link](<foo
7599	bar>)
7600	.
7601	<p>[link](<foo
7602	bar>)</p>
7603	````````````````````````````````
7604
7605	The destination can contain `)` if it is enclosed
7606	in pointy brackets:
7607
7608	```````````````````````````````` example
7609	[a](<b)c>)
7610	.
7611	<p><a href="b)c">a</a></p>
7612	````````````````````````````````
7613
7614	Pointy brackets that enclose links must be unescaped:
7615
7616	```````````````````````````````` example
7617	[link](<foo\>)
7618	.
7619	<p>[link](&lt;foo&gt;)</p>
7620	````````````````````````````````
7621
7622	These are not links, because the opening pointy bracket
7623	is not matched properly:
7624
7625	```````````````````````````````` example
7626	[a](<b)c
7627	[a](<b)c>
7628	[a](<b>c)
7629	.
7630	<p>[a](&lt;b)c
7631	[a](&lt;b)c&gt;
7632	[a](<b>c)</p>
7633	````````````````````````````````
7634
7635	Parentheses inside the link destination may be escaped:
7636
7637	```````````````````````````````` example
7638	[link](\(foo\))
7639	.
7640	<p><a href="(foo)">link</a></p>
7641	````````````````````````````````
7642
7643	Any number of parentheses are allowed without escaping, as long as they are
7644	balanced:
7645
7646	```````````````````````````````` example
7647	[link](foo(and(bar)))
7648	.
7649	<p><a href="foo(and(bar))">link</a></p>
7650	````````````````````````````````
7651
7652	However, if you have unbalanced parentheses, you need to escape or use the
7653	`<...>` form:
7654
7655	```````````````````````````````` example
7656	[link](foo(and(bar))
7657	.
7658	<p>[link](foo(and(bar))</p>
7659	````````````````````````````````
7660
7661
7662	```````````````````````````````` example
7663	[link](foo\(and\(bar\))
7664	.
7665	<p><a href="foo(and(bar)">link</a></p>
7666	````````````````````````````````
7667
7668
7669	```````````````````````````````` example
7670	[link](<foo(and(bar)>)
7671	.
7672	<p><a href="foo(and(bar)">link</a></p>
7673	````````````````````````````````
7674
7675
7676	Parentheses and other symbols can also be escaped, as usual
7677	in Markdown:
7678
7679	```````````````````````````````` example
7680	[link](foo\)\:)
7681	.
7682	<p><a href="foo):">link</a></p>
7683	````````````````````````````````
7684
7685
7686	A link can contain fragment identifiers and queries:
7687
7688	```````````````````````````````` example
7689	[link](#fragment)
7690
7691	[link](http://example.com#fragment)
7692
7693	[link](http://example.com?foo=3#frag)
7694	.
7695	<p><a href="#fragment">link</a></p>
7696	<p><a href="http://example.com#fragment">link</a></p>
7697	<p><a href="http://example.com?foo=3#frag">link</a></p>
7698	````````````````````````````````
7699
7700
7701	Note that a backslash before a non-escapable character is
7702	just a backslash:
7703
7704	```````````````````````````````` example
7705	[link](foo\bar)
7706	.
7707	<p><a href="foo%5Cbar">link</a></p>
7708	````````````````````````````````
7709
7710
7711	URL-escaping should be left alone inside the destination, as all
7712	URL-escaped characters are also valid URL characters. Entity and
7713	numerical character references in the destination will be parsed
7714	into the corresponding Unicode code points, as usual. These may
7715	be optionally URL-escaped when written as HTML, but this spec
7716	does not enforce any particular policy for rendering URLs in
7717	HTML or other formats. Renderers may make different decisions
7718	about how to escape or normalize URLs in the output.
7719
7720	```````````````````````````````` example
7721	[link](foo%20b&auml;)
7722	.
7723	<p><a href="foo%20b%C3%A4">link</a></p>
7724	````````````````````````````````
7725
7726
7727	Note that, because titles can often be parsed as destinations,
7728	if you try to omit the destination and keep the title, you'll
7729	get unexpected results:
7730
7731	```````````````````````````````` example
7732	[link]("title")
7733	.
7734	<p><a href="%22title%22">link</a></p>
7735	````````````````````````````````
7736
7737
7738	Titles may be in single quotes, double quotes, or parentheses:
7739
7740	```````````````````````````````` example
7741	[link](/url "title")
7742	[link](/url 'title')
7743	[link](/url (title))
7744	.
7745	<p><a href="/url" title="title">link</a>
7746	<a href="/url" title="title">link</a>
7747	<a href="/url" title="title">link</a></p>
7748	````````````````````````````````
7749
7750
7751	Backslash escapes and entity and numeric character references
7752	may be used in titles:
7753
7754	```````````````````````````````` example
7755	[link](/url "title \"&quot;")
7756	.
7757	<p><a href="/url" title="title &quot;&quot;">link</a></p>
7758	````````````````````````````````
7759
7760
7761	Titles must be separated from the link using spaces, tabs, and up to one line
7762	ending.
7763	Other [Unicode whitespace] like non-breaking space doesn't work.
7764
7765	```````````````````````````````` example
7766	[link](/url "title")
7767	.
7768	<p><a href="/url%C2%A0%22title%22">link</a></p>
7769	````````````````````````````````
7770
7771
7772	Nested balanced quotes are not allowed without escaping:
7773
7774	```````````````````````````````` example
7775	[link](/url "title "and" title")
7776	.
7777	<p>[link](/url &quot;title &quot;and&quot; title&quot;)</p>
7778	````````````````````````````````
7779
7780
7781	But it is easy to work around this by using a different quote type:
7782
7783	```````````````````````````````` example
7784	[link](/url 'title "and" title')
7785	.
7786	<p><a href="/url" title="title &quot;and&quot; title">link</a></p>
7787	````````````````````````````````
7788
7789
7790	(Note: `Markdown.pl` did allow double quotes inside a double-quoted
7791	title, and its test suite included a test demonstrating this.
7792	But it is hard to see a good rationale for the extra complexity this
7793	brings, since there are already many ways---backslash escaping,
7794	entity and numeric character references, or using a different
7795	quote type for the enclosing title---to write titles containing
7796	double quotes. `Markdown.pl`'s handling of titles has a number
7797	of other strange features. For example, it allows single-quoted
7798	titles in inline links, but not reference links. And, in
7799	reference links but not inline links, it allows a title to begin
7800	with `"` and end with `)`. `Markdown.pl` 1.0.1 even allows
7801	titles with no closing quotation mark, though 1.0.2b8 does not.
7802	It seems preferable to adopt a simple, rational rule that works
7803	the same way in inline links and link reference definitions.)
7804
7805	Spaces, tabs, and up to one line ending is allowed around the destination and
7806	title:
7807
7808	```````````````````````````````` example
7809	[link]( /uri
7810	"title" )
7811	.
7812	<p><a href="/uri" title="title">link</a></p>
7813	````````````````````````````````
7814
7815
7816	But it is not allowed between the link text and the
7817	following parenthesis:
7818
7819	```````````````````````````````` example
7820	[link] (/uri)
7821	.
7822	<p>[link] (/uri)</p>
7823	````````````````````````````````
7824
7825
7826	The link text may contain balanced brackets, but not unbalanced ones,
7827	unless they are escaped:
7828
7829	```````````````````````````````` example
7830	[link [foo [bar]]](/uri)
7831	.
7832	<p><a href="/uri">link [foo [bar]]</a></p>
7833	````````````````````````````````
7834
7835
7836	```````````````````````````````` example
7837	[link] bar](/uri)
7838	.
7839	<p>[link] bar](/uri)</p>
7840	````````````````````````````````
7841
7842
7843	```````````````````````````````` example
7844	[link [bar](/uri)
7845	.
7846	<p>[link <a href="/uri">bar</a></p>
7847	````````````````````````````````
7848
7849
7850	```````````````````````````````` example
7851	[link \[bar](/uri)
7852	.
7853	<p><a href="/uri">link [bar</a></p>
7854	````````````````````````````````
7855
7856
7857	The link text may contain inline content:
7858
7859	```````````````````````````````` example
7860	[link *foo **bar** `#`*](/uri)
7861	.
7862	<p><a href="/uri">link <em>foo <strong>bar</strong> <code>#</code></em></a></p>
7863	````````````````````````````````
7864
7865
7866	```````````````````````````````` example
7867	[](/uri)
7868	.
7869	<p><a href="/uri"><img src="moon.jpg" alt="moon" /></a></p>
7870	````````````````````````````````
7871
7872
7873	However, links may not contain other links, at any level of nesting.
7874
7875	```````````````````````````````` example
7876	[foo [bar](/uri)](/uri)
7877	.
7878	<p>[foo <a href="/uri">bar</a>](/uri)</p>
7879	````````````````````````````````
7880
7881
7882	```````````````````````````````` example
7883	[foo *[bar [baz](/uri)](/uri)*](/uri)
7884	.
7885	<p>[foo <em>[bar <a href="/uri">baz</a>](/uri)</em>](/uri)</p>
7886	````````````````````````````````
7887
7888
7889	```````````````````````````````` example
7890	](uri2)](uri3)
7891	.
7892	<p><img src="uri3" alt="[foo](uri2)" /></p>
7893	````````````````````````````````
7894
7895
7896	These cases illustrate the precedence of link text grouping over
7897	emphasis grouping:
7898
7899	```````````````````````````````` example
7900	*[foo*](/uri)
7901	.
7902	<p>*<a href="/uri">foo*</a></p>
7903	````````````````````````````````
7904
7905
7906	```````````````````````````````` example
7907	[foo *bar](baz*)
7908	.
7909	<p><a href="baz*">foo *bar</a></p>
7910	````````````````````````````````
7911
7912
7913	Note that brackets that *aren't* part of links do not take
7914	precedence:
7915
7916	```````````````````````````````` example
7917	*foo [bar* baz]
7918	.
7919	<p><em>foo [bar</em> baz]</p>
7920	````````````````````````````````
7921
7922
7923	These cases illustrate the precedence of HTML tags, code spans,
7924	and autolinks over link grouping:
7925
7926	```````````````````````````````` example
7927	[foo <bar attr="](baz)">
7928	.
7929	<p>[foo <bar attr="](baz)"></p>
7930	````````````````````````````````
7931
7932
7933	```````````````````````````````` example
7934	[foo`](/uri)`
7935	.
7936	<p>[foo<code>](/uri)</code></p>
7937	````````````````````````````````
7938
7939
7940	```````````````````````````````` example
7941	[foo<http://example.com/?search=](uri)>
7942	.
7943	<p>[foo<a href="http://example.com/?search=%5D(uri)">http://example.com/?search=](uri)</a></p>
7944	````````````````````````````````
7945
7946
7947	There are three kinds of [reference link](@)s:
7948	[full](#full-reference-link), [collapsed](#collapsed-reference-link),
7949	and [shortcut](#shortcut-reference-link).
7950
7951	A [full reference link](@)
7952	consists of a [link text] immediately followed by a [link label]
7953	that [matches] a [link reference definition] elsewhere in the document.
7954
7955	A [link label](@) begins with a left bracket (`[`) and ends
7956	with the first right bracket (`]`) that is not backslash-escaped.
7957	Between these brackets there must be at least one character that is not a space,
7958	tab, or line ending.
7959	Unescaped square bracket characters are not allowed inside the
7960	opening and closing square brackets of [link labels]. A link
7961	label can have at most 999 characters inside the square
7962	brackets.
7963
7964	One label [matches](@)
7965	another just in case their normalized forms are equal. To normalize a
7966	label, strip off the opening and closing brackets,
7967	perform the *Unicode case fold*, strip leading and trailing
7968	spaces, tabs, and line endings, and collapse consecutive internal
7969	spaces, tabs, and line endings to a single space. If there are multiple
7970	matching reference link definitions, the one that comes first in the
7971	document is used. (It is desirable in such cases to emit a warning.)
7972
7973	The link's URI and title are provided by the matching [link
7974	reference definition].
7975
7976	Here is a simple example:
7977
7978	```````````````````````````````` example
7979	[foo][bar]
7980
7981	[bar]: /url "title"
7982	.
7983	<p><a href="/url" title="title">foo</a></p>
7984	````````````````````````````````
7985
7986
7987	The rules for the [link text] are the same as with
7988	[inline links]. Thus:
7989
7990	The link text may contain balanced brackets, but not unbalanced ones,
7991	unless they are escaped:
7992
7993	```````````````````````````````` example
7994	[link [foo [bar]]][ref]
7995
7996	[ref]: /uri
7997	.
7998	<p><a href="/uri">link [foo [bar]]</a></p>
7999	````````````````````````````````
8000
8001
8002	```````````````````````````````` example
8003	[link \[bar][ref]
8004
8005	[ref]: /uri
8006	.
8007	<p><a href="/uri">link [bar</a></p>
8008	````````````````````````````````
8009
8010
8011	The link text may contain inline content:
8012
8013	```````````````````````````````` example
8014	[link *foo **bar** `#`*][ref]
8015
8016	[ref]: /uri
8017	.
8018	<p><a href="/uri">link <em>foo <strong>bar</strong> <code>#</code></em></a></p>
8019	````````````````````````````````
8020
8021
8022	```````````````````````````````` example
8023	[][ref]
8024
8025	[ref]: /uri
8026	.
8027	<p><a href="/uri"><img src="moon.jpg" alt="moon" /></a></p>
8028	````````````````````````````````
8029
8030
8031	However, links may not contain other links, at any level of nesting.
8032
8033	```````````````````````````````` example
8034	[foo [bar](/uri)][ref]
8035
8036	[ref]: /uri
8037	.
8038	<p>[foo <a href="/uri">bar</a>]<a href="/uri">ref</a></p>
8039	````````````````````````````````
8040
8041
8042	```````````````````````````````` example
8043	[foo *bar [baz][ref]*][ref]
8044
8045	[ref]: /uri
8046	.
8047	<p>[foo <em>bar <a href="/uri">baz</a></em>]<a href="/uri">ref</a></p>
8048	````````````````````````````````
8049
8050
8051	(In the examples above, we have two [shortcut reference links]
8052	instead of one [full reference link].)
8053
8054	The following cases illustrate the precedence of link text grouping over
8055	emphasis grouping:
8056
8057	```````````````````````````````` example
8058	*[foo*][ref]
8059
8060	[ref]: /uri
8061	.
8062	<p>*<a href="/uri">foo*</a></p>
8063	````````````````````````````````
8064
8065
8066	```````````````````````````````` example
8067	[foo *bar][ref]*
8068
8069	[ref]: /uri
8070	.
8071	<p><a href="/uri">foo *bar</a>*</p>
8072	````````````````````````````````
8073
8074
8075	These cases illustrate the precedence of HTML tags, code spans,
8076	and autolinks over link grouping:
8077
8078	```````````````````````````````` example
8079	[foo <bar attr="][ref]">
8080
8081	[ref]: /uri
8082	.
8083	<p>[foo <bar attr="][ref]"></p>
8084	````````````````````````````````
8085
8086
8087	```````````````````````````````` example
8088	[foo`][ref]`
8089
8090	[ref]: /uri
8091	.
8092	<p>[foo<code>][ref]</code></p>
8093	````````````````````````````````
8094
8095
8096	```````````````````````````````` example
8097	[foo<http://example.com/?search=][ref]>
8098
8099	[ref]: /uri
8100	.
8101	<p>[foo<a href="http://example.com/?search=%5D%5Bref%5D">http://example.com/?search=][ref]</a></p>
8102	````````````````````````````````
8103
8104
8105	Matching is case-insensitive:
8106
8107	```````````````````````````````` example
8108	[foo][BaR]
8109
8110	[bar]: /url "title"
8111	.
8112	<p><a href="/url" title="title">foo</a></p>
8113	````````````````````````````````
8114
8115
8116	Unicode case fold is used:
8117
8118	```````````````````````````````` example
8119	[ẞ]
8120
8121	[SS]: /url
8122	.
8123	<p><a href="/url">ẞ</a></p>
8124	````````````````````````````````
8125
8126
8127	Consecutive internal spaces, tabs, and line endings are treated as one space for
8128	purposes of determining matching:
8129
8130	```````````````````````````````` example
8131	[Foo
8132	bar]: /url
8133
8134	[Baz][Foo bar]
8135	.
8136	<p><a href="/url">Baz</a></p>
8137	````````````````````````````````
8138
8139
8140	No spaces, tabs, or line endings are allowed between the [link text] and the
8141	[link label]:
8142
8143	```````````````````````````````` example
8144	[foo] [bar]
8145
8146	[bar]: /url "title"
8147	.
8148	<p>[foo] <a href="/url" title="title">bar</a></p>
8149	````````````````````````````````
8150
8151
8152	```````````````````````````````` example
8153	[foo]
8154	[bar]
8155
8156	[bar]: /url "title"
8157	.
8158	<p>[foo]
8159	<a href="/url" title="title">bar</a></p>
8160	````````````````````````````````
8161
8162
8163	This is a departure from John Gruber's original Markdown syntax
8164	description, which explicitly allows whitespace between the link
8165	text and the link label. It brings reference links in line with
8166	[inline links], which (according to both original Markdown and
8167	this spec) cannot have whitespace after the link text. More
8168	importantly, it prevents inadvertent capture of consecutive
8169	[shortcut reference links]. If whitespace is allowed between the
8170	link text and the link label, then in the following we will have
8171	a single reference link, not two shortcut reference links, as
8172	intended:
8173
8174	``` markdown
8175	[foo]
8176	[bar]
8177
8178	[foo]: /url1
8179	[bar]: /url2
8180	```
8181
8182	(Note that [shortcut reference links] were introduced by Gruber
8183	himself in a beta version of `Markdown.pl`, but never included
8184	in the official syntax description. Without shortcut reference
8185	links, it is harmless to allow space between the link text and
8186	link label; but once shortcut references are introduced, it is
8187	too dangerous to allow this, as it frequently leads to
8188	unintended results.)
8189
8190	When there are multiple matching [link reference definitions],
8191	the first is used:
8192
8193	```````````````````````````````` example
8194	[foo]: /url1
8195
8196	[foo]: /url2
8197
8198	[bar][foo]
8199	.
8200	<p><a href="/url1">bar</a></p>
8201	````````````````````````````````
8202
8203
8204	Note that matching is performed on normalized strings, not parsed
8205	inline content. So the following does not match, even though the
8206	labels define equivalent inline content:
8207
8208	```````````````````````````````` example
8209	[bar][foo\!]
8210
8211	[foo!]: /url
8212	.
8213	<p>[bar][foo!]</p>
8214	````````````````````````````````
8215
8216
8217	[Link labels] cannot contain brackets, unless they are
8218	backslash-escaped:
8219
8220	```````````````````````````````` example
8221	[foo][ref[]
8222
8223	[ref[]: /uri
8224	.
8225	<p>[foo][ref[]</p>
8226	<p>[ref[]: /uri</p>
8227	````````````````````````````````
8228
8229
8230	```````````````````````````````` example
8231	[foo][ref[bar]]
8232
8233	[ref[bar]]: /uri
8234	.
8235	<p>[foo][ref[bar]]</p>
8236	<p>[ref[bar]]: /uri</p>
8237	````````````````````````````````
8238
8239
8240	```````````````````````````````` example
8241	[[[foo]]]
8242
8243	[[[foo]]]: /url
8244	.
8245	<p>[[[foo]]]</p>
8246	<p>[[[foo]]]: /url</p>
8247	````````````````````````````````
8248
8249
8250	```````````````````````````````` example
8251	[foo][ref\[]
8252
8253	[ref\[]: /uri
8254	.
8255	<p><a href="/uri">foo</a></p>
8256	````````````````````````````````
8257
8258
8259	Note that in this example `]` is not backslash-escaped:
8260
8261	```````````````````````````````` example
8262	[bar\\]: /uri
8263
8264	[bar\\]
8265	.
8266	<p><a href="/uri">bar\</a></p>
8267	````````````````````````````````
8268
8269
8270	A [link label] must contain at least one character that is not a space, tab, or
8271	line ending:
8272
8273	```````````````````````````````` example
8274	[]
8275
8276	[]: /uri
8277	.
8278	<p>[]</p>
8279	<p>[]: /uri</p>
8280	````````````````````````````````
8281
8282
8283	```````````````````````````````` example
8284	[
8285	]
8286
8287	[
8288	]: /uri
8289	.
8290	<p>[
8291	]</p>
8292	<p>[
8293	]: /uri</p>
8294	````````````````````````````````
8295
8296
8297	A [collapsed reference link](@)
8298	consists of a [link label] that [matches] a
8299	[link reference definition] elsewhere in the
8300	document, followed by the string `[]`.
8301	The contents of the first link label are parsed as inlines,
8302	which are used as the link's text. The link's URI and title are
8303	provided by the matching reference link definition. Thus,
8304	`[foo][]` is equivalent to `[foo][foo]`.
8305
8306	```````````````````````````````` example
8307	[foo][]
8308
8309	[foo]: /url "title"
8310	.
8311	<p><a href="/url" title="title">foo</a></p>
8312	````````````````````````````````
8313
8314
8315	```````````````````````````````` example
8316	[*foo* bar][]
8317
8318	[*foo* bar]: /url "title"
8319	.
8320	<p><a href="/url" title="title"><em>foo</em> bar</a></p>
8321	````````````````````````````````
8322
8323
8324	The link labels are case-insensitive:
8325
8326	```````````````````````````````` example
8327	[Foo][]
8328
8329	[foo]: /url "title"
8330	.
8331	<p><a href="/url" title="title">Foo</a></p>
8332	````````````````````````````````
8333
8334
8335
8336	As with full reference links, spaces, tabs, or line endings are not
8337	allowed between the two sets of brackets:
8338
8339	```````````````````````````````` example
8340	[foo]
8341	[]
8342
8343	[foo]: /url "title"
8344	.
8345	<p><a href="/url" title="title">foo</a>
8346	[]</p>
8347	````````````````````````````````
8348
8349
8350	A [shortcut reference link](@)
8351	consists of a [link label] that [matches] a
8352	[link reference definition] elsewhere in the
8353	document and is not followed by `[]` or a link label.
8354	The contents of the first link label are parsed as inlines,
8355	which are used as the link's text. The link's URI and title
8356	are provided by the matching link reference definition.
8357	Thus, `[foo]` is equivalent to `[foo][]`.
8358
8359	```````````````````````````````` example
8360	[foo]
8361
8362	[foo]: /url "title"
8363	.
8364	<p><a href="/url" title="title">foo</a></p>
8365	````````````````````````````````
8366
8367
8368	```````````````````````````````` example
8369	[*foo* bar]
8370
8371	[*foo* bar]: /url "title"
8372	.
8373	<p><a href="/url" title="title"><em>foo</em> bar</a></p>
8374	````````````````````````````````
8375
8376
8377	```````````````````````````````` example
8378	[[*foo* bar]]
8379
8380	[*foo* bar]: /url "title"
8381	.
8382	<p>[<a href="/url" title="title"><em>foo</em> bar</a>]</p>
8383	````````````````````````````````
8384
8385
8386	```````````````````````````````` example
8387	[[bar [foo]
8388
8389	[foo]: /url
8390	.
8391	<p>[[bar <a href="/url">foo</a></p>
8392	````````````````````````````````
8393
8394
8395	The link labels are case-insensitive:
8396
8397	```````````````````````````````` example
8398	[Foo]
8399
8400	[foo]: /url "title"
8401	.
8402	<p><a href="/url" title="title">Foo</a></p>
8403	````````````````````````````````
8404
8405
8406	A space after the link text should be preserved:
8407
8408	```````````````````````````````` example
8409	[foo] bar
8410
8411	[foo]: /url
8412	.
8413	<p><a href="/url">foo</a> bar</p>
8414	````````````````````````````````
8415
8416
8417	If you just want bracketed text, you can backslash-escape the
8418	opening bracket to avoid links:
8419
8420	```````````````````````````````` example
8421	\[foo]
8422
8423	[foo]: /url "title"
8424	.
8425	<p>[foo]</p>
8426	````````````````````````````````
8427
8428
8429	Note that this is a link, because a link label ends with the first
8430	following closing bracket:
8431
8432	```````````````````````````````` example
8433	[foo*]: /url
8434
8435	*[foo*]
8436	.
8437	<p>*<a href="/url">foo*</a></p>
8438	````````````````````````````````
8439
8440
8441	Full and compact references take precedence over shortcut
8442	references:
8443
8444	```````````````````````````````` example
8445	[foo][bar]
8446
8447	[foo]: /url1
8448	[bar]: /url2
8449	.
8450	<p><a href="/url2">foo</a></p>
8451	````````````````````````````````
8452
8453	```````````````````````````````` example
8454	[foo][]
8455
8456	[foo]: /url1
8457	.
8458	<p><a href="/url1">foo</a></p>
8459	````````````````````````````````
8460
8461	Inline links also take precedence:
8462
8463	```````````````````````````````` example
8464	[foo]()
8465
8466	[foo]: /url1
8467	.
8468	<p><a href="">foo</a></p>
8469	````````````````````````````````
8470
8471	```````````````````````````````` example
8472	[foo](not a link)
8473
8474	[foo]: /url1
8475	.
8476	<p><a href="/url1">foo</a>(not a link)</p>
8477	````````````````````````````````
8478
8479	In the following case `[bar][baz]` is parsed as a reference,
8480	`[foo]` as normal text:
8481
8482	```````````````````````````````` example
8483	[foo][bar][baz]
8484
8485	[baz]: /url
8486	.
8487	<p>[foo]<a href="/url">bar</a></p>
8488	````````````````````````````````
8489
8490
8491	Here, though, `[foo][bar]` is parsed as a reference, since
8492	`[bar]` is defined:
8493
8494	```````````````````````````````` example
8495	[foo][bar][baz]
8496
8497	[baz]: /url1
8498	[bar]: /url2
8499	.
8500	<p><a href="/url2">foo</a><a href="/url1">baz</a></p>
8501	````````````````````````````````
8502
8503
8504	Here `[foo]` is not parsed as a shortcut reference, because it
8505	is followed by a link label (even though `[bar]` is not defined):
8506
8507	```````````````````````````````` example
8508	[foo][bar][baz]
8509
8510	[baz]: /url1
8511	[foo]: /url2
8512	.
8513	<p>[foo]<a href="/url1">bar</a></p>
8514	````````````````````````````````
8515
8516
8517
8518	## Images
8519
8520	Syntax for images is like the syntax for links, with one
8521	difference. Instead of [link text], we have an
8522	[image description](@). The rules for this are the
8523	same as for [link text], except that (a) an
8524	image description starts with `![` rather than `[`, and
8525	(b) an image description may contain links.
8526	An image description has inline elements
8527	as its contents. When an image is rendered to HTML,
8528	this is standardly used as the image's `alt` attribute.
8529
8530	```````````````````````````````` example
8531	
8532	.
8533	<p><img src="/url" alt="foo" title="title" /></p>
8534	````````````````````````````````
8535
8536
8537	```````````````````````````````` example
8538	![foo *bar*]
8539
8540	[foo *bar*]: train.jpg "train & tracks"
8541	.
8542	<p><img src="train.jpg" alt="foo bar" title="train &amp; tracks" /></p>
8543	````````````````````````````````
8544
8545
8546	```````````````````````````````` example
8547	](/url2)
8548	.
8549	<p><img src="/url2" alt="foo bar" /></p>
8550	````````````````````````````````
8551
8552
8553	```````````````````````````````` example
8554	](/url2)
8555	.
8556	<p><img src="/url2" alt="foo bar" /></p>
8557	````````````````````````````````
8558
8559
8560	Though this spec is concerned with parsing, not rendering, it is
8561	recommended that in rendering to HTML, only the plain string content
8562	of the [image description] be used. Note that in
8563	the above example, the alt attribute's value is `foo bar`, not `foo
8564	[bar](/url)` or `foo <a href="/url">bar</a>`. Only the plain string
8565	content is rendered, without formatting.
8566
8567	```````````````````````````````` example
8568	![foo *bar*][]
8569
8570	[foo *bar*]: train.jpg "train & tracks"
8571	.
8572	<p><img src="train.jpg" alt="foo bar" title="train &amp; tracks" /></p>
8573	````````````````````````````````
8574
8575
8576	```````````````````````````````` example
8577	![foo *bar*][foobar]
8578
8579	[FOOBAR]: train.jpg "train & tracks"
8580	.
8581	<p><img src="train.jpg" alt="foo bar" title="train &amp; tracks" /></p>
8582	````````````````````````````````
8583
8584
8585	```````````````````````````````` example
8586	
8587	.
8588	<p><img src="train.jpg" alt="foo" /></p>
8589	````````````````````````````````
8590
8591
8592	```````````````````````````````` example
8593	My 
8594	.
8595	<p>My <img src="/path/to/train.jpg" alt="foo bar" title="title" /></p>
8596	````````````````````````````````
8597
8598
8599	```````````````````````````````` example
8600	
8601	.
8602	<p><img src="url" alt="foo" /></p>
8603	````````````````````````````````
8604
8605
8606	```````````````````````````````` example
8607	
8608	.
8609	<p><img src="/url" alt="" /></p>
8610	````````````````````````````````
8611
8612
8613	Reference-style:
8614
8615	```````````````````````````````` example
8616	![foo][bar]
8617
8618	[bar]: /url
8619	.
8620	<p><img src="/url" alt="foo" /></p>
8621	````````````````````````````````
8622
8623
8624	```````````````````````````````` example
8625	![foo][bar]
8626
8627	[BAR]: /url
8628	.
8629	<p><img src="/url" alt="foo" /></p>
8630	````````````````````````````````
8631
8632
8633	Collapsed:
8634
8635	```````````````````````````````` example
8636	![foo][]
8637
8638	[foo]: /url "title"
8639	.
8640	<p><img src="/url" alt="foo" title="title" /></p>
8641	````````````````````````````````
8642
8643
8644	```````````````````````````````` example
8645	![*foo* bar][]
8646
8647	[*foo* bar]: /url "title"
8648	.
8649	<p><img src="/url" alt="foo bar" title="title" /></p>
8650	````````````````````````````````
8651
8652
8653	The labels are case-insensitive:
8654
8655	```````````````````````````````` example
8656	![Foo][]
8657
8658	[foo]: /url "title"
8659	.
8660	<p><img src="/url" alt="Foo" title="title" /></p>
8661	````````````````````````````````
8662
8663
8664	As with reference links, spaces, tabs, and line endings, are not allowed
8665	between the two sets of brackets:
8666
8667	```````````````````````````````` example
8668	![foo]
8669	[]
8670
8671	[foo]: /url "title"
8672	.
8673	<p><img src="/url" alt="foo" title="title" />
8674	[]</p>
8675	````````````````````````````````
8676
8677
8678	Shortcut:
8679
8680	```````````````````````````````` example
8681	![foo]
8682
8683	[foo]: /url "title"
8684	.
8685	<p><img src="/url" alt="foo" title="title" /></p>
8686	````````````````````````````````
8687
8688
8689	```````````````````````````````` example
8690	![*foo* bar]
8691
8692	[*foo* bar]: /url "title"
8693	.
8694	<p><img src="/url" alt="foo bar" title="title" /></p>
8695	````````````````````````````````
8696
8697
8698	Note that link labels cannot contain unescaped brackets:
8699
8700	```````````````````````````````` example
8701	![[foo]]
8702
8703	[[foo]]: /url "title"
8704	.
8705	<p>![[foo]]</p>
8706	<p>[[foo]]: /url &quot;title&quot;</p>
8707	````````````````````````````````
8708
8709
8710	The link labels are case-insensitive:
8711
8712	```````````````````````````````` example
8713	![Foo]
8714
8715	[foo]: /url "title"
8716	.
8717	<p><img src="/url" alt="Foo" title="title" /></p>
8718	````````````````````````````````
8719
8720
8721	If you just want a literal `!` followed by bracketed text, you can
8722	backslash-escape the opening `[`:
8723
8724	```````````````````````````````` example
8725	!\[foo]
8726
8727	[foo]: /url "title"
8728	.
8729	<p>![foo]</p>
8730	````````````````````````````````
8731
8732
8733	If you want a link after a literal `!`, backslash-escape the
8734	`!`:
8735
8736	```````````````````````````````` example
8737	\![foo]
8738
8739	[foo]: /url "title"
8740	.
8741	<p>!<a href="/url" title="title">foo</a></p>
8742	````````````````````````````````
8743
8744
8745	## Autolinks
8746
8747	[Autolink](@)s are absolute URIs and email addresses inside
8748	`<` and `>`. They are parsed as links, with the URL or email address
8749	as the link label.
8750
8751	A [URI autolink](@) consists of `<`, followed by an
8752	[absolute URI] followed by `>`. It is parsed as
8753	a link to the URI, with the URI as the link's label.
8754
8755	An [absolute URI](@),
8756	for these purposes, consists of a [scheme] followed by a colon (`:`)
8757	followed by zero or more characters other [ASCII control
8758	characters][ASCII control character], [space], `<`, and `>`.
8759	If the URI includes these characters, they must be percent-encoded
8760	(e.g. `%20` for a space).
8761
8762	For purposes of this spec, a [scheme](@) is any sequence
8763	of 2--32 characters beginning with an ASCII letter and followed
8764	by any combination of ASCII letters, digits, or the symbols plus
8765	("+"), period ("."), or hyphen ("-").
8766
8767	Here are some valid autolinks:
8768
8769	```````````````````````````````` example
8770	<http://foo.bar.baz>
8771	.
8772	<p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p>
8773	````````````````````````````````
8774
8775
8776	```````````````````````````````` example
8777	<http://foo.bar.baz/test?q=hello&id=22&boolean>
8778	.
8779	<p><a href="http://foo.bar.baz/test?q=hello&amp;id=22&amp;boolean">http://foo.bar.baz/test?q=hello&amp;id=22&amp;boolean</a></p>
8780	````````````````````````````````
8781
8782
8783	```````````````````````````````` example
8784	<irc://foo.bar:2233/baz>
8785	.
8786	<p><a href="irc://foo.bar:2233/baz">irc://foo.bar:2233/baz</a></p>
8787	````````````````````````````````
8788
8789
8790	Uppercase is also fine:
8791
8792	```````````````````````````````` example
8793	<MAILTO:FOO@BAR.BAZ>
8794	.
8795	<p><a href="MAILTO:FOO@BAR.BAZ">MAILTO:FOO@BAR.BAZ</a></p>
8796	````````````````````````````````
8797
8798
8799	Note that many strings that count as [absolute URIs] for
8800	purposes of this spec are not valid URIs, because their
8801	schemes are not registered or because of other problems
8802	with their syntax:
8803
8804	```````````````````````````````` example
8805	<a+b+c:d>
8806	.
8807	<p><a href="a+b+c:d">a+b+c:d</a></p>
8808	````````````````````````````````
8809
8810
8811	```````````````````````````````` example
8812	<made-up-scheme://foo,bar>
8813	.
8814	<p><a href="made-up-scheme://foo,bar">made-up-scheme://foo,bar</a></p>
8815	````````````````````````````````
8816
8817
8818	```````````````````````````````` example
8819	<http://../>
8820	.
8821	<p><a href="http://../">http://../</a></p>
8822	````````````````````````````````
8823
8824
8825	```````````````````````````````` example
8826	<localhost:5001/foo>
8827	.
8828	<p><a href="localhost:5001/foo">localhost:5001/foo</a></p>
8829	````````````````````````````````
8830
8831
8832	Spaces are not allowed in autolinks:
8833
8834	```````````````````````````````` example
8835	<http://foo.bar/baz bim>
8836	.
8837	<p>&lt;http://foo.bar/baz bim&gt;</p>
8838	````````````````````````````````
8839
8840
8841	Backslash-escapes do not work inside autolinks:
8842
8843	```````````````````````````````` example
8844	<http://example.com/\[\>
8845	.
8846	<p><a href="http://example.com/%5C%5B%5C">http://example.com/\[\</a></p>
8847	````````````````````````````````
8848
8849
8850	An [email autolink](@)
8851	consists of `<`, followed by an [email address],
8852	followed by `>`. The link's label is the email address,
8853	and the URL is `mailto:` followed by the email address.
8854
8855	An [email address](@),
8856	for these purposes, is anything that matches
8857	the [non-normative regex from the HTML5
8858	spec](https://html.spec.whatwg.org/multipage/forms.html#e-mail-state-(type=email)):
8859
8860	/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?
8861	(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/
8862
8863	Examples of email autolinks:
8864
8865	```````````````````````````````` example
8866	<foo@bar.example.com>
8867	.
8868	<p><a href="mailto:foo@bar.example.com">foo@bar.example.com</a></p>
8869	````````````````````````````````
8870
8871
8872	```````````````````````````````` example
8873	<foo+special@Bar.baz-bar0.com>
8874	.
8875	<p><a href="mailto:foo+special@Bar.baz-bar0.com">foo+special@Bar.baz-bar0.com</a></p>
8876	````````````````````````````````
8877
8878
8879	Backslash-escapes do not work inside email autolinks:
8880
8881	```````````````````````````````` example
8882	<foo\+@bar.example.com>
8883	.
8884	<p>&lt;foo+@bar.example.com&gt;</p>
8885	````````````````````````````````
8886
8887
8888	These are not autolinks:
8889
8890	```````````````````````````````` example
8891	<>
8892	.
8893	<p>&lt;&gt;</p>
8894	````````````````````````````````
8895
8896
8897	```````````````````````````````` example
8898	< http://foo.bar >
8899	.
8900	<p>&lt; http://foo.bar &gt;</p>
8901	````````````````````````````````
8902
8903
8904	```````````````````````````````` example
8905	<m:abc>
8906	.
8907	<p>&lt;m:abc&gt;</p>
8908	````````````````````````````````
8909
8910
8911	```````````````````````````````` example
8912	<foo.bar.baz>
8913	.
8914	<p>&lt;foo.bar.baz&gt;</p>
8915	````````````````````````````````
8916
8917
8918	```````````````````````````````` example
8919	http://example.com
8920	.
8921	<p>http://example.com</p>
8922	````````````````````````````````
8923
8924
8925	```````````````````````````````` example
8926	foo@bar.example.com
8927	.
8928	<p>foo@bar.example.com</p>
8929	````````````````````````````````
8930
8931
8932	## Raw HTML
8933
8934	Text between `<` and `>` that looks like an HTML tag is parsed as a
8935	raw HTML tag and will be rendered in HTML without escaping.
8936	Tag and attribute names are not limited to current HTML tags,
8937	so custom tags (and even, say, DocBook tags) may be used.
8938
8939	Here is the grammar for tags:
8940
8941	A [tag name](@) consists of an ASCII letter
8942	followed by zero or more ASCII letters, digits, or
8943	hyphens (`-`).
8944
8945	An [attribute](@) consists of spaces, tabs, and up to one line ending,
8946	an [attribute name], and an optional
8947	[attribute value specification].
8948
8949	An [attribute name](@)
8950	consists of an ASCII letter, `_`, or `:`, followed by zero or more ASCII
8951	letters, digits, `_`, `.`, `:`, or `-`. (Note: This is the XML
8952	specification restricted to ASCII. HTML5 is laxer.)
8953
8954	An [attribute value specification](@)
8955	consists of optional spaces, tabs, and up to one line ending,
8956	a `=` character, optional spaces, tabs, and up to one line ending,
8957	and an [attribute value].
8958
8959	An [attribute value](@)
8960	consists of an [unquoted attribute value],
8961	a [single-quoted attribute value], or a [double-quoted attribute value].
8962
8963	An [unquoted attribute value](@)
8964	is a nonempty string of characters not
8965	including spaces, tabs, line endings, `"`, `'`, `=`, `<`, `>`, or `` ` ``.
8966
8967	A [single-quoted attribute value](@)
8968	consists of `'`, zero or more
8969	characters not including `'`, and a final `'`.
8970
8971	A [double-quoted attribute value](@)
8972	consists of `"`, zero or more
8973	characters not including `"`, and a final `"`.
8974
8975	An [open tag](@) consists of a `<` character, a [tag name],
8976	zero or more [attributes], optional spaces, tabs, and up to one line ending,
8977	an optional `/` character, and a `>` character.
8978
8979	A [closing tag](@) consists of the string `</`, a
8980	[tag name], optional spaces, tabs, and up to one line ending, and the character
8981	`>`.
8982
8983	An [HTML comment](@) consists of `<!--` + *text* + `-->`,
8984	where *text* does not start with `>` or `->`, does not end with `-`,
8985	and does not contain `--`. (See the
8986	[HTML5 spec](http://www.w3.org/TR/html5/syntax.html#comments).)
8987
8988	A [processing instruction](@)
8989	consists of the string `<?`, a string
8990	of characters not including the string `?>`, and the string
8991	`?>`.
8992
8993	A [declaration](@) consists of the string `<!`, an ASCII letter, zero or more
8994	characters not including the character `>`, and the character `>`.
8995
8996	A [CDATA section](@) consists of
8997	the string `<![CDATA[`, a string of characters not including the string
8998	`]]>`, and the string `]]>`.
8999
9000	An [HTML tag](@) consists of an [open tag], a [closing tag],
9001	an [HTML comment], a [processing instruction], a [declaration],
9002	or a [CDATA section].
9003
9004	Here are some simple open tags:
9005
9006	```````````````````````````````` example
9007	<a><bab><c2c>
9008	.
9009	<p><a><bab><c2c></p>
9010	````````````````````````````````
9011
9012
9013	Empty elements:
9014
9015	```````````````````````````````` example
9016	<a/><b2/>
9017	.
9018	<p><a/><b2/></p>
9019	````````````````````````````````
9020
9021
9022	Whitespace is allowed:
9023
9024	```````````````````````````````` example
9025	<a /><b2
9026	data="foo" >
9027	.
9028	<p><a /><b2
9029	data="foo" ></p>
9030	````````````````````````````````
9031
9032
9033	With attributes:
9034
9035	```````````````````````````````` example
9036	<a foo="bar" bam = 'baz <em>"</em>'
9037	_boolean zoop:33=zoop:33 />
9038	.
9039	<p><a foo="bar" bam = 'baz <em>"</em>'
9040	_boolean zoop:33=zoop:33 /></p>
9041	````````````````````````````````
9042
9043
9044	Custom tag names can be used:
9045
9046	```````````````````````````````` example
9047	Foo <responsive-image src="foo.jpg" />
9048	.
9049	<p>Foo <responsive-image src="foo.jpg" /></p>
9050	````````````````````````````````
9051
9052
9053	Illegal tag names, not parsed as HTML:
9054
9055	```````````````````````````````` example
9056	<33> <__>
9057	.
9058	<p>&lt;33&gt; &lt;__&gt;</p>
9059	````````````````````````````````
9060
9061
9062	Illegal attribute names:
9063
9064	```````````````````````````````` example
9065	<a h*#ref="hi">
9066	.
9067	<p>&lt;a h*#ref=&quot;hi&quot;&gt;</p>
9068	````````````````````````````````
9069
9070
9071	Illegal attribute values:
9072
9073	```````````````````````````````` example
9074	<a href="hi'> <a href=hi'>
9075	.
9076	<p>&lt;a href=&quot;hi'&gt; &lt;a href=hi'&gt;</p>
9077	````````````````````````````````
9078
9079
9080	Illegal whitespace:
9081
9082	```````````````````````````````` example
9083	< a><
9084	foo><bar/ >
9085	<foo bar=baz
9086	bim!bop />
9087	.
9088	<p>&lt; a&gt;&lt;
9089	foo&gt;&lt;bar/ &gt;
9090	&lt;foo bar=baz
9091	bim!bop /&gt;</p>
9092	````````````````````````````````
9093
9094
9095	Missing whitespace:
9096
9097	```````````````````````````````` example
9098	<a href='bar'title=title>
9099	.
9100	<p>&lt;a href='bar'title=title&gt;</p>
9101	````````````````````````````````
9102
9103
9104	Closing tags:
9105
9106	```````````````````````````````` example
9107	</a></foo >
9108	.
9109	<p></a></foo ></p>
9110	````````````````````````````````
9111
9112
9113	Illegal attributes in closing tag:
9114
9115	```````````````````````````````` example
9116	</a href="foo">
9117	.
9118	<p>&lt;/a href=&quot;foo&quot;&gt;</p>
9119	````````````````````````````````
9120
9121
9122	Comments:
9123
9124	```````````````````````````````` example
9125	foo <!-- this is a
9126	comment - with hyphen -->
9127	.
9128	<p>foo <!-- this is a
9129	comment - with hyphen --></p>
9130	````````````````````````````````
9131
9132
9133	```````````````````````````````` example
9134	foo <!-- not a comment -- two hyphens -->
9135	.
9136	<p>foo &lt;!-- not a comment -- two hyphens --&gt;</p>
9137	````````````````````````````````
9138
9139
9140	Not comments:
9141
9142	```````````````````````````````` example
9143	foo <!--> foo -->
9144
9145	foo <!-- foo--->
9146	.
9147	<p>foo &lt;!--&gt; foo --&gt;</p>
9148	<p>foo &lt;!-- foo---&gt;</p>
9149	````````````````````````````````
9150
9151
9152	Processing instructions:
9153
9154	```````````````````````````````` example
9155	foo <?php echo $a; ?>
9156	.
9157	<p>foo <?php echo $a; ?></p>
9158	````````````````````````````````
9159
9160
9161	Declarations:
9162
9163	```````````````````````````````` example
9164	foo <!ELEMENT br EMPTY>
9165	.
9166	<p>foo <!ELEMENT br EMPTY></p>
9167	````````````````````````````````
9168
9169
9170	CDATA sections:
9171
9172	```````````````````````````````` example
9173	foo <![CDATA[>&<]]>
9174	.
9175	<p>foo <![CDATA[>&<]]></p>
9176	````````````````````````````````
9177
9178
9179	Entity and numeric character references are preserved in HTML
9180	attributes:
9181
9182	```````````````````````````````` example
9183	foo <a href="&ouml;">
9184	.
9185	<p>foo <a href="&ouml;"></p>
9186	````````````````````````````````
9187
9188
9189	Backslash escapes do not work in HTML attributes:
9190
9191	```````````````````````````````` example
9192	foo <a href="\*">
9193	.
9194	<p>foo <a href="\*"></p>
9195	````````````````````````````````
9196
9197
9198	```````````````````````````````` example
9199	<a href="\"">
9200	.
9201	<p>&lt;a href=&quot;&quot;&quot;&gt;</p>
9202	````````````````````````````````
9203
9204
9205	## Hard line breaks
9206
9207	A line ending (not in a code span or HTML tag) that is preceded
9208	by two or more spaces and does not occur at the end of a block
9209	is parsed as a [hard line break](@) (rendered
9210	in HTML as a `<br />` tag):
9211
9212	```````````````````````````````` example
9213	foo
9214	baz
9215	.
9216	<p>foo<br />
9217	baz</p>
9218	````````````````````````````````
9219
9220
9221	For a more visible alternative, a backslash before the
9222	[line ending] may be used instead of two or more spaces:
9223
9224	```````````````````````````````` example
9225	foo\
9226	baz
9227	.
9228	<p>foo<br />
9229	baz</p>
9230	````````````````````````````````
9231
9232
9233	More than two spaces can be used:
9234
9235	```````````````````````````````` example
9236	foo
9237	baz
9238	.
9239	<p>foo<br />
9240	baz</p>
9241	````````````````````````````````
9242
9243
9244	Leading spaces at the beginning of the next line are ignored:
9245
9246	```````````````````````````````` example
9247	foo
9248	bar
9249	.
9250	<p>foo<br />
9251	bar</p>
9252	````````````````````````````````
9253
9254
9255	```````````````````````````````` example
9256	foo\
9257	bar
9258	.
9259	<p>foo<br />
9260	bar</p>
9261	````````````````````````````````
9262
9263
9264	Hard line breaks can occur inside emphasis, links, and other constructs
9265	that allow inline content:
9266
9267	```````````````````````````````` example
9268	*foo
9269	bar*
9270	.
9271	<p><em>foo<br />
9272	bar</em></p>
9273	````````````````````````````````
9274
9275
9276	```````````````````````````````` example
9277	*foo\
9278	bar*
9279	.
9280	<p><em>foo<br />
9281	bar</em></p>
9282	````````````````````````````````
9283
9284
9285	Hard line breaks do not occur inside code spans
9286
9287	```````````````````````````````` example
9288	`code
9289	span`
9290	.
9291	<p><code>code span</code></p>
9292	````````````````````````````````
9293
9294
9295	```````````````````````````````` example
9296	`code\
9297	span`
9298	.
9299	<p><code>code\ span</code></p>
9300	````````````````````````````````
9301
9302
9303	or HTML tags:
9304
9305	```````````````````````````````` example
9306	<a href="foo
9307	bar">
9308	.
9309	<p><a href="foo
9310	bar"></p>
9311	````````````````````````````````
9312
9313
9314	```````````````````````````````` example
9315	<a href="foo\
9316	bar">
9317	.
9318	<p><a href="foo\
9319	bar"></p>
9320	````````````````````````````````
9321
9322
9323	Hard line breaks are for separating inline content within a block.
9324	Neither syntax for hard line breaks works at the end of a paragraph or
9325	other block element:
9326
9327	```````````````````````````````` example
9328	foo\
9329	.
9330	<p>foo\</p>
9331	````````````````````````````````
9332
9333
9334	```````````````````````````````` example
9335	foo
9336	.
9337	<p>foo</p>
9338	````````````````````````````````
9339
9340
9341	```````````````````````````````` example
9342	### foo\
9343	.
9344	<h3>foo\</h3>
9345	````````````````````````````````
9346
9347
9348	```````````````````````````````` example
9349	### foo
9350	.
9351	<h3>foo</h3>
9352	````````````````````````````````
9353
9354
9355	## Soft line breaks
9356
9357	A regular line ending (not in a code span or HTML tag) that is not
9358	preceded by two or more spaces or a backslash is parsed as a
9359	[softbreak](@). (A soft line break may be rendered in HTML either as a
9360	[line ending] or as a space. The result will be the same in
9361	browsers. In the examples here, a [line ending] will be used.)
9362
9363	```````````````````````````````` example
9364	foo
9365	baz
9366	.
9367	<p>foo
9368	baz</p>
9369	````````````````````````````````
9370
9371
9372	Spaces at the end of the line and beginning of the next line are
9373	removed:
9374
9375	```````````````````````````````` example
9376	foo
9377	baz
9378	.
9379	<p>foo
9380	baz</p>
9381	````````````````````````````````
9382
9383
9384	A conforming parser may render a soft line break in HTML either as a
9385	line ending or as a space.
9386
9387	A renderer may also provide an option to render soft line breaks
9388	as hard line breaks.
9389
9390	## Textual content
9391
9392	Any characters not given an interpretation by the above rules will
9393	be parsed as plain textual content.
9394
9395	```````````````````````````````` example
9396	hello $.;'there
9397	.
9398	<p>hello $.;'there</p>
9399	````````````````````````````````
9400
9401
9402	```````````````````````````````` example
9403	Foo χρῆν
9404	.
9405	<p>Foo χρῆν</p>
9406	````````````````````````````````
9407
9408
9409	Internal spaces are preserved verbatim:
9410
9411	```````````````````````````````` example
9412	Multiple spaces
9413	.
9414	<p>Multiple spaces</p>
9415	````````````````````````````````
9416
9417
9418	<!-- END TESTS -->
9419
9420	# Appendix: A parsing strategy
9421
9422	In this appendix we describe some features of the parsing strategy
9423	used in the CommonMark reference implementations.
9424
9425	## Overview
9426
9427	Parsing has two phases:
9428
9429	1. In the first phase, lines of input are consumed and the block
9430	structure of the document---its division into paragraphs, block quotes,
9431	list items, and so on---is constructed. Text is assigned to these
9432	blocks but not parsed. Link reference definitions are parsed and a
9433	map of links is constructed.
9434
9435	2. In the second phase, the raw text contents of paragraphs and headings
9436	are parsed into sequences of Markdown inline elements (strings,
9437	code spans, links, emphasis, and so on), using the map of link
9438	references constructed in phase 1.
9439
9440	At each point in processing, the document is represented as a tree of
9441	**blocks**. The root of the tree is a `document` block. The `document`
9442	may have any number of other blocks as **children**. These children
9443	may, in turn, have other blocks as children. The last child of a block
9444	is normally considered **open**, meaning that subsequent lines of input
9445	can alter its contents. (Blocks that are not open are **closed**.)
9446	Here, for example, is a possible document tree, with the open blocks
9447	marked by arrows:
9448
9449	``` tree
9450	-> document
9451	-> block_quote
9452	paragraph
9453	"Lorem ipsum dolor\nsit amet."
9454	-> list (type=bullet tight=true bullet_char=-)
9455	list_item
9456	paragraph
9457	"Qui *quodsi iracundia*"
9458	-> list_item
9459	-> paragraph
9460	"aliquando id"
9461	```
9462
9463	## Phase 1: block structure
9464
9465	Each line that is processed has an effect on this tree. The line is
9466	analyzed and, depending on its contents, the document may be altered
9467	in one or more of the following ways:
9468
9469	1. One or more open blocks may be closed.
9470	2. One or more new blocks may be created as children of the
9471	last open block.
9472	3. Text may be added to the last (deepest) open block remaining
9473	on the tree.
9474
9475	Once a line has been incorporated into the tree in this way,
9476	it can be discarded, so input can be read in a stream.
9477
9478	For each line, we follow this procedure:
9479
9480	1. First we iterate through the open blocks, starting with the
9481	root document, and descending through last children down to the last
9482	open block. Each block imposes a condition that the line must satisfy
9483	if the block is to remain open. For example, a block quote requires a
9484	`>` character. A paragraph requires a non-blank line.
9485	In this phase we may match all or just some of the open
9486	blocks. But we cannot close unmatched blocks yet, because we may have a
9487	[lazy continuation line].
9488
9489	2. Next, after consuming the continuation markers for existing
9490	blocks, we look for new block starts (e.g. `>` for a block quote).
9491	If we encounter a new block start, we close any blocks unmatched
9492	in step 1 before creating the new block as a child of the last
9493	matched container block.
9494
9495	3. Finally, we look at the remainder of the line (after block
9496	markers like `>`, list markers, and indentation have been consumed).
9497	This is text that can be incorporated into the last open
9498	block (a paragraph, code block, heading, or raw HTML).
9499
9500	Setext headings are formed when we see a line of a paragraph
9501	that is a [setext heading underline].
9502
9503	Reference link definitions are detected when a paragraph is closed;
9504	the accumulated text lines are parsed to see if they begin with
9505	one or more reference link definitions. Any remainder becomes a
9506	normal paragraph.
9507
9508	We can see how this works by considering how the tree above is
9509	generated by four lines of Markdown:
9510
9511	``` markdown
9512	> Lorem ipsum dolor
9513	sit amet.
9514	> - Qui *quodsi iracundia*
9515	> - aliquando id
9516	```
9517
9518	At the outset, our document model is just
9519
9520	``` tree
9521	-> document
9522	```
9523
9524	The first line of our text,
9525
9526	``` markdown
9527	> Lorem ipsum dolor
9528	```
9529
9530	causes a `block_quote` block to be created as a child of our
9531	open `document` block, and a `paragraph` block as a child of
9532	the `block_quote`. Then the text is added to the last open
9533	block, the `paragraph`:
9534
9535	``` tree
9536	-> document
9537	-> block_quote
9538	-> paragraph
9539	"Lorem ipsum dolor"
9540	```
9541
9542	The next line,
9543
9544	``` markdown
9545	sit amet.
9546	```
9547
9548	is a "lazy continuation" of the open `paragraph`, so it gets added
9549	to the paragraph's text:
9550
9551	``` tree
9552	-> document
9553	-> block_quote
9554	-> paragraph
9555	"Lorem ipsum dolor\nsit amet."
9556	```
9557
9558	The third line,
9559
9560	``` markdown
9561	> - Qui *quodsi iracundia*
9562	```
9563
9564	causes the `paragraph` block to be closed, and a new `list` block
9565	opened as a child of the `block_quote`. A `list_item` is also
9566	added as a child of the `list`, and a `paragraph` as a child of
9567	the `list_item`. The text is then added to the new `paragraph`:
9568
9569	``` tree
9570	-> document
9571	-> block_quote
9572	paragraph
9573	"Lorem ipsum dolor\nsit amet."
9574	-> list (type=bullet tight=true bullet_char=-)
9575	-> list_item
9576	-> paragraph
9577	"Qui *quodsi iracundia*"
9578	```
9579
9580	The fourth line,
9581
9582	``` markdown
9583	> - aliquando id
9584	```
9585
9586	causes the `list_item` (and its child the `paragraph`) to be closed,
9587	and a new `list_item` opened up as child of the `list`. A `paragraph`
9588	is added as a child of the new `list_item`, to contain the text.
9589	We thus obtain the final tree:
9590
9591	``` tree
9592	-> document
9593	-> block_quote
9594	paragraph
9595	"Lorem ipsum dolor\nsit amet."
9596	-> list (type=bullet tight=true bullet_char=-)
9597	list_item
9598	paragraph
9599	"Qui *quodsi iracundia*"
9600	-> list_item
9601	-> paragraph
9602	"aliquando id"
9603	```
9604
9605	## Phase 2: inline structure
9606
9607	Once all of the input has been parsed, all open blocks are closed.
9608
9609	We then "walk the tree," visiting every node, and parse raw
9610	string contents of paragraphs and headings as inlines. At this
9611	point we have seen all the link reference definitions, so we can
9612	resolve reference links as we go.
9613
9614	``` tree
9615	document
9616	block_quote
9617	paragraph
9618	str "Lorem ipsum dolor"
9619	softbreak
9620	str "sit amet."
9621	list (type=bullet tight=true bullet_char=-)
9622	list_item
9623	paragraph
9624	str "Qui "
9625	emph
9626	str "quodsi iracundia"
9627	list_item
9628	paragraph
9629	str "aliquando id"
9630	```
9631
9632	Notice how the [line ending] in the first paragraph has
9633	been parsed as a `softbreak`, and the asterisks in the first list item
9634	have become an `emph`.
9635
9636	### An algorithm for parsing nested emphasis and links
9637
9638	By far the trickiest part of inline parsing is handling emphasis,
9639	strong emphasis, links, and images. This is done using the following
9640	algorithm.
9641
9642	When we're parsing inlines and we hit either
9643
9644	- a run of `*` or `_` characters, or
9645	- a `[` or `![`
9646
9647	we insert a text node with these symbols as its literal content, and we
9648	add a pointer to this text node to the [delimiter stack](@).
9649
9650	The [delimiter stack] is a doubly linked list. Each
9651	element contains a pointer to a text node, plus information about
9652
9653	- the type of delimiter (`[`, `![`, `*`, `_`)
9654	- the number of delimiters,
9655	- whether the delimiter is "active" (all are active to start), and
9656	- whether the delimiter is a potential opener, a potential closer,
9657	or both (which depends on what sort of characters precede
9658	and follow the delimiters).
9659
9660	When we hit a `]` character, we call the *look for link or image*
9661	procedure (see below).
9662
9663	When we hit the end of the input, we call the *process emphasis*
9664	procedure (see below), with `stack_bottom` = NULL.
9665
9666	#### *look for link or image*
9667
9668	Starting at the top of the delimiter stack, we look backwards
9669	through the stack for an opening `[` or `![` delimiter.
9670
9671	- If we don't find one, we return a literal text node `]`.
9672
9673	- If we do find one, but it's not *active*, we remove the inactive
9674	delimiter from the stack, and return a literal text node `]`.
9675
9676	- If we find one and it's active, then we parse ahead to see if
9677	we have an inline link/image, reference link/image, compact reference
9678	link/image, or shortcut reference link/image.
9679
9680	+ If we don't, then we remove the opening delimiter from the
9681	delimiter stack and return a literal text node `]`.
9682
9683	+ If we do, then
9684
9685	* We return a link or image node whose children are the inlines
9686	after the text node pointed to by the opening delimiter.
9687
9688	* We run *process emphasis* on these inlines, with the `[` opener
9689	as `stack_bottom`.
9690
9691	* We remove the opening delimiter.
9692
9693	* If we have a link (and not an image), we also set all
9694	`[` delimiters before the opening delimiter to *inactive*. (This
9695	will prevent us from getting links within links.)
9696
9697	#### *process emphasis*
9698
9699	Parameter `stack_bottom` sets a lower bound to how far we
9700	descend in the [delimiter stack]. If it is NULL, we can
9701	go all the way to the bottom. Otherwise, we stop before
9702	visiting `stack_bottom`.
9703
9704	Let `current_position` point to the element on the [delimiter stack]
9705	just above `stack_bottom` (or the first element if `stack_bottom`
9706	is NULL).
9707
9708	We keep track of the `openers_bottom` for each delimiter
9709	type (`*`, `_`), indexed to the length of the closing delimiter run
9710	(modulo 3) and to whether the closing delimiter can also be an
9711	opener. Initialize this to `stack_bottom`.
9712
9713	Then we repeat the following until we run out of potential
9714	closers:
9715
9716	- Move `current_position` forward in the delimiter stack (if needed)
9717	until we find the first potential closer with delimiter `*` or `_`.
9718	(This will be the potential closer closest
9719	to the beginning of the input -- the first one in parse order.)
9720
9721	- Now, look back in the stack (staying above `stack_bottom` and
9722	the `openers_bottom` for this delimiter type) for the
9723	first matching potential opener ("matching" means same delimiter).
9724
9725	- If one is found:
9726
9727	+ Figure out whether we have emphasis or strong emphasis:
9728	if both closer and opener spans have length >= 2, we have
9729	strong, otherwise regular.
9730
9731	+ Insert an emph or strong emph node accordingly, after
9732	the text node corresponding to the opener.
9733
9734	+ Remove any delimiters between the opener and closer from
9735	the delimiter stack.
9736
9737	+ Remove 1 (for regular emph) or 2 (for strong emph) delimiters
9738	from the opening and closing text nodes. If they become empty
9739	as a result, remove them and remove the corresponding element
9740	of the delimiter stack. If the closing node is removed, reset
9741	`current_position` to the next element in the stack.
9742
9743	- If none is found:
9744
9745	+ Set `openers_bottom` to the element before `current_position`.
9746	(We know that there are no openers for this kind of closer up to and
9747	including this point, so this puts a lower bound on future searches.)
9748
9749	+ If the closer at `current_position` is not a potential opener,
9750	remove it from the delimiter stack (since we know it can't
9751	be a closer either).
9752
9753	+ Advance `current_position` to the next element in the stack.
9754
9755	After we're done, we remove all delimiters above `stack_bottom` from the
9756	delimiter stack.