aboutsummaryrefslogtreecommitdiff
path: root/spec.txt
blob: 12ec4824407b131cce5872bccbaa6945545fe188 (plain)
  1. ---
  2. title: CommonMark Spec
  3. author:
  4. - John MacFarlane
  5. version: 0.5
  6. date: 2014-10-25
  7. ...
  8. # Introduction
  9. ## What is Markdown?
  10. Markdown is a plain text format for writing structured documents,
  11. based on conventions used for indicating formatting in email and
  12. usenet posts. It was developed in 2004 by John Gruber, who wrote
  13. the first Markdown-to-HTML converter in perl, and it soon became
  14. widely used in websites. By 2014 there were dozens of
  15. implementations in many languages. Some of them extended basic
  16. Markdown syntax with conventions for footnotes, definition lists,
  17. tables, and other constructs, and some allowed output not just in
  18. HTML but in LaTeX and many other formats.
  19. ## Why is a spec needed?
  20. John Gruber's [canonical description of Markdown's
  21. syntax](http://daringfireball.net/projects/markdown/syntax)
  22. does not specify the syntax unambiguously. Here are some examples of
  23. questions it does not answer:
  24. 1. How much indentation is needed for a sublist? The spec says that
  25. continuation paragraphs need to be indented four spaces, but is
  26. not fully explicit about sublists. It is natural to think that
  27. they, too, must be indented four spaces, but `Markdown.pl` does
  28. not require that. This is hardly a "corner case," and divergences
  29. between implementations on this issue often lead to surprises for
  30. users in real documents. (See [this comment by John
  31. Gruber](http://article.gmane.org/gmane.text.markdown.general/1997).)
  32. 2. Is a blank line needed before a block quote or header?
  33. Most implementations do not require the blank line. However,
  34. this can lead to unexpected results in hard-wrapped text, and
  35. also to ambiguities in parsing (note that some implementations
  36. put the header inside the blockquote, while others do not).
  37. (John Gruber has also spoken [in favor of requiring the blank
  38. lines](http://article.gmane.org/gmane.text.markdown.general/2146).)
  39. 3. Is a blank line needed before an indented code block?
  40. (`Markdown.pl` requires it, but this is not mentioned in the
  41. documentation, and some implementations do not require it.)
  42. ``` markdown
  43. paragraph
  44. code?
  45. ```
  46. 4. What is the exact rule for determining when list items get
  47. wrapped in `<p>` tags? Can a list be partially "loose" and partially
  48. "tight"? What should we do with a list like this?
  49. ``` markdown
  50. 1. one
  51. 2. two
  52. 3. three
  53. ```
  54. Or this?
  55. ``` markdown
  56. 1. one
  57. - a
  58. - b
  59. 2. two
  60. ```
  61. (There are some relevant comments by John Gruber
  62. [here](http://article.gmane.org/gmane.text.markdown.general/2554).)
  63. 5. Can list markers be indented? Can ordered list markers be right-aligned?
  64. ``` markdown
  65. 8. item 1
  66. 9. item 2
  67. 10. item 2a
  68. ```
  69. 6. Is this one list with a horizontal rule in its second item,
  70. or two lists separated by a horizontal rule?
  71. ``` markdown
  72. * a
  73. * * * * *
  74. * b
  75. ```
  76. 7. When list markers change from numbers to bullets, do we have
  77. two lists or one? (The Markdown syntax description suggests two,
  78. but the perl scripts and many other implementations produce one.)
  79. ``` markdown
  80. 1. fee
  81. 2. fie
  82. - foe
  83. - fum
  84. ```
  85. 8. What are the precedence rules for the markers of inline structure?
  86. For example, is the following a valid link, or does the code span
  87. take precedence ?
  88. ``` markdown
  89. [a backtick (`)](/url) and [another backtick (`)](/url).
  90. ```
  91. 9. What are the precedence rules for markers of emphasis and strong
  92. emphasis? For example, how should the following be parsed?
  93. ``` markdown
  94. *foo *bar* baz*
  95. ```
  96. 10. What are the precedence rules between block-level and inline-level
  97. structure? For example, how should the following be parsed?
  98. ``` markdown
  99. - `a long code span can contain a hyphen like this
  100. - and it can screw things up`
  101. ```
  102. 11. Can list items include headers? (`Markdown.pl` does not allow this,
  103. but headers can occur in blockquotes.)
  104. ``` markdown
  105. - # Heading
  106. ```
  107. 12. Can link references be defined inside block quotes or list items?
  108. ``` markdown
  109. > Blockquote [foo].
  110. >
  111. > [foo]: /url
  112. ```
  113. 13. If there are multiple definitions for the same reference, which takes
  114. precedence?
  115. ``` markdown
  116. [foo]: /url1
  117. [foo]: /url2
  118. [foo][]
  119. ```
  120. In the absence of a spec, early implementers consulted `Markdown.pl`
  121. to resolve these ambiguities. But `Markdown.pl` was quite buggy, and
  122. gave manifestly bad results in many cases, so it was not a
  123. satisfactory replacement for a spec.
  124. Because there is no unambiguous spec, implementations have diverged
  125. considerably. As a result, users are often surprised to find that
  126. a document that renders one way on one system (say, a github wiki)
  127. renders differently on another (say, converting to docbook using
  128. pandoc). To make matters worse, because nothing in Markdown counts
  129. as a "syntax error," the divergence often isn't discovered right away.
  130. ## About this document
  131. This document attempts to specify Markdown syntax unambiguously.
  132. It contains many examples with side-by-side Markdown and
  133. HTML. These are intended to double as conformance tests. An
  134. accompanying script `runtests.pl` can be used to run the tests
  135. against any Markdown program:
  136. perl runtests.pl spec.txt PROGRAM
  137. Since this document describes how Markdown is to be parsed into
  138. an abstract syntax tree, it would have made sense to use an abstract
  139. representation of the syntax tree instead of HTML. But HTML is capable
  140. of representing the structural distinctions we need to make, and the
  141. choice of HTML for the tests makes it possible to run the tests against
  142. an implementation without writing an abstract syntax tree renderer.
  143. This document is generated from a text file, `spec.txt`, written
  144. in Markdown with a small extension for the side-by-side tests.
  145. The script `spec2md.pl` can be used to turn `spec.txt` into pandoc
  146. Markdown, which can then be converted into other formats.
  147. In the examples, the `→` character is used to represent tabs.
  148. # Preprocessing
  149. A [line](#line) <a id="line"></a>
  150. is a sequence of zero or more [characters](#character) followed by a
  151. line ending (CR, LF, or CRLF) or by the end of file.
  152. A [character](#character)<a id="character"></a> is a unicode code point.
  153. This spec does not specify an encoding; it thinks of lines as composed
  154. of characters rather than bytes. A conforming parser may be limited
  155. to a certain encoding.
  156. Tabs in lines are expanded to spaces, with a tab stop of 4 characters:
  157. .
  158. →foo→baz→→bim
  159. .
  160. <pre><code>foo baz bim
  161. </code></pre>
  162. .
  163. .
  164. a→a
  165. ὐ→a
  166. .
  167. <pre><code>a a
  168. ὐ a
  169. </code></pre>
  170. .
  171. Line endings are replaced by newline characters (LF).
  172. A line containing no characters, or a line containing only spaces (after
  173. tab expansion), is called a [blank line](#blank-line).
  174. <a id="blank-line"></a>
  175. # Blocks and inlines
  176. We can think of a document as a sequence of [blocks](#block)<a
  177. id="block"></a>---structural elements like paragraphs, block quotations,
  178. lists, headers, rules, and code blocks. Blocks can contain other
  179. blocks, or they can contain [inline](#inline)<a id="inline"></a> content:
  180. words, spaces, links, emphasized text, images, and inline code.
  181. ## Precedence
  182. Indicators of block structure always take precedence over indicators
  183. of inline structure. So, for example, the following is a list with
  184. two items, not a list with one item containing a code span:
  185. .
  186. - `one
  187. - two`
  188. .
  189. <ul>
  190. <li>`one</li>
  191. <li>two`</li>
  192. </ul>
  193. .
  194. This means that parsing can proceed in two steps: first, the block
  195. structure of the document can be discerned; second, text lines inside
  196. paragraphs, headers, and other block constructs can be parsed for inline
  197. structure. The second step requires information about link reference
  198. definitions that will be available only at the end of the first
  199. step. Note that the first step requires processing lines in sequence,
  200. but the second can be parallelized, since the inline parsing of
  201. one block element does not affect the inline parsing of any other.
  202. ## Container blocks and leaf blocks
  203. We can divide blocks into two types:
  204. [container blocks](#container-block), <a id="container-block"></a>
  205. which can contain other blocks, and [leaf blocks](#leaf-block),
  206. <a id="leaf-block"></a> which cannot.
  207. # Leaf blocks
  208. This section describes the different kinds of leaf block that make up a
  209. Markdown document.
  210. ## Horizontal rules
  211. A line consisting of 0-3 spaces of indentation, followed by a sequence
  212. of three or more matching `-`, `_`, or `*` characters, each followed
  213. optionally by any number of spaces, forms a [horizontal
  214. rule](#horizontal-rule). <a id="horizontal-rule"></a>
  215. .
  216. ***
  217. ---
  218. ___
  219. .
  220. <hr />
  221. <hr />
  222. <hr />
  223. .
  224. Wrong characters:
  225. .
  226. +++
  227. .
  228. <p>+++</p>
  229. .
  230. .
  231. ===
  232. .
  233. <p>===</p>
  234. .
  235. Not enough characters:
  236. .
  237. --
  238. **
  239. __
  240. .
  241. <p>--
  242. **
  243. __</p>
  244. .
  245. One to three spaces indent are allowed:
  246. .
  247. ***
  248. ***
  249. ***
  250. .
  251. <hr />
  252. <hr />
  253. <hr />
  254. .
  255. Four spaces is too many:
  256. .
  257. ***
  258. .
  259. <pre><code>***
  260. </code></pre>
  261. .
  262. .
  263. Foo
  264. ***
  265. .
  266. <p>Foo
  267. ***</p>
  268. .
  269. More than three characters may be used:
  270. .
  271. _____________________________________
  272. .
  273. <hr />
  274. .
  275. Spaces are allowed between the characters:
  276. .
  277. - - -
  278. .
  279. <hr />
  280. .
  281. .
  282. ** * ** * ** * **
  283. .
  284. <hr />
  285. .
  286. .
  287. - - - -
  288. .
  289. <hr />
  290. .
  291. Spaces are allowed at the end:
  292. .
  293. - - - -
  294. .
  295. <hr />
  296. .
  297. However, no other characters may occur in the line:
  298. .
  299. _ _ _ _ a
  300. a------
  301. ---a---
  302. .
  303. <p>_ _ _ _ a</p>
  304. <p>a------</p>
  305. <p>---a---</p>
  306. .
  307. It is required that all of the non-space characters be the same.
  308. So, this is not a horizontal rule:
  309. .
  310. *-*
  311. .
  312. <p><em>-</em></p>
  313. .
  314. Horizontal rules do not need blank lines before or after:
  315. .
  316. - foo
  317. ***
  318. - bar
  319. .
  320. <ul>
  321. <li>foo</li>
  322. </ul>
  323. <hr />
  324. <ul>
  325. <li>bar</li>
  326. </ul>
  327. .
  328. Horizontal rules can interrupt a paragraph:
  329. .
  330. Foo
  331. ***
  332. bar
  333. .
  334. <p>Foo</p>
  335. <hr />
  336. <p>bar</p>
  337. .
  338. If a line of dashes that meets the above conditions for being a
  339. horizontal rule could also be interpreted as the underline of a [setext
  340. header](#setext-header), the interpretation as a
  341. [setext-header](#setext-header) takes precedence. Thus, for example,
  342. this is a setext header, not a paragraph followed by a horizontal rule:
  343. .
  344. Foo
  345. ---
  346. bar
  347. .
  348. <h2>Foo</h2>
  349. <p>bar</p>
  350. .
  351. When both a horizontal rule and a list item are possible
  352. interpretations of a line, the horizontal rule is preferred:
  353. .
  354. * Foo
  355. * * *
  356. * Bar
  357. .
  358. <ul>
  359. <li>Foo</li>
  360. </ul>
  361. <hr />
  362. <ul>
  363. <li>Bar</li>
  364. </ul>
  365. .
  366. If you want a horizontal rule in a list item, use a different bullet:
  367. .
  368. - Foo
  369. - * * *
  370. .
  371. <ul>
  372. <li>Foo</li>
  373. <li><hr /></li>
  374. </ul>
  375. .
  376. ## ATX headers
  377. An [ATX header](#atx-header) <a id="atx-header"></a>
  378. consists of a string of characters, parsed as inline content, between an
  379. opening sequence of 1--6 unescaped `#` characters and an optional
  380. closing sequence of any number of `#` characters. The opening sequence
  381. of `#` characters cannot be followed directly by a nonspace character.
  382. The closing `#` characters may be followed by spaces only. The opening
  383. `#` character may be indented 0-3 spaces. The raw contents of the
  384. header are stripped of leading and trailing spaces before being parsed
  385. as inline content. The header level is equal to the number of `#`
  386. characters in the opening sequence.
  387. Simple headers:
  388. .
  389. # foo
  390. ## foo
  391. ### foo
  392. #### foo
  393. ##### foo
  394. ###### foo
  395. .
  396. <h1>foo</h1>
  397. <h2>foo</h2>
  398. <h3>foo</h3>
  399. <h4>foo</h4>
  400. <h5>foo</h5>
  401. <h6>foo</h6>
  402. .
  403. More than six `#` characters is not a header:
  404. .
  405. ####### foo
  406. .
  407. <p>####### foo</p>
  408. .
  409. A space is required between the `#` characters and the header's
  410. contents. Note that many implementations currently do not require
  411. the space. However, the space was required by the [original ATX
  412. implementation](http://www.aaronsw.com/2002/atx/atx.py), and it helps
  413. prevent things like the following from being parsed as headers:
  414. .
  415. #5 bolt
  416. .
  417. <p>#5 bolt</p>
  418. .
  419. This is not a header, because the first `#` is escaped:
  420. .
  421. \## foo
  422. .
  423. <p>## foo</p>
  424. .
  425. Contents are parsed as inlines:
  426. .
  427. # foo *bar* \*baz\*
  428. .
  429. <h1>foo <em>bar</em> *baz*</h1>
  430. .
  431. Leading and trailing blanks are ignored in parsing inline content:
  432. .
  433. # foo
  434. .
  435. <h1>foo</h1>
  436. .
  437. One to three spaces indentation are allowed:
  438. .
  439. ### foo
  440. ## foo
  441. # foo
  442. .
  443. <h3>foo</h3>
  444. <h2>foo</h2>
  445. <h1>foo</h1>
  446. .
  447. Four spaces are too much:
  448. .
  449. # foo
  450. .
  451. <pre><code># foo
  452. </code></pre>
  453. .
  454. .
  455. foo
  456. # bar
  457. .
  458. <p>foo
  459. # bar</p>
  460. .
  461. A closing sequence of `#` characters is optional:
  462. .
  463. ## foo ##
  464. ### bar ###
  465. .
  466. <h2>foo</h2>
  467. <h3>bar</h3>
  468. .
  469. It need not be the same length as the opening sequence:
  470. .
  471. # foo ##################################
  472. ##### foo ##
  473. .
  474. <h1>foo</h1>
  475. <h5>foo</h5>
  476. .
  477. Spaces are allowed after the closing sequence:
  478. .
  479. ### foo ###
  480. .
  481. <h3>foo</h3>
  482. .
  483. A sequence of `#` characters with a nonspace character following it
  484. is not a closing sequence, but counts as part of the contents of the
  485. header:
  486. .
  487. ### foo ### b
  488. .
  489. <h3>foo ### b</h3>
  490. .
  491. Backslash-escaped `#` characters do not count as part
  492. of the closing sequence:
  493. .
  494. ### foo \###
  495. ## foo \#\##
  496. # foo \#
  497. .
  498. <h3>foo #</h3>
  499. <h2>foo ##</h2>
  500. <h1>foo #</h1>
  501. .
  502. ATX headers need not be separated from surrounding content by blank
  503. lines, and they can interrupt paragraphs:
  504. .
  505. ****
  506. ## foo
  507. ****
  508. .
  509. <hr />
  510. <h2>foo</h2>
  511. <hr />
  512. .
  513. .
  514. Foo bar
  515. # baz
  516. Bar foo
  517. .
  518. <p>Foo bar</p>
  519. <h1>baz</h1>
  520. <p>Bar foo</p>
  521. .
  522. ATX headers can be empty:
  523. .
  524. ##
  525. #
  526. ### ###
  527. .
  528. <h2></h2>
  529. <h1></h1>
  530. <h3></h3>
  531. .
  532. ## Setext headers
  533. A [setext header](#setext-header) <a id="setext-header"></a>
  534. consists of a line of text, containing at least one nonspace character,
  535. with no more than 3 spaces indentation, followed by a [setext header
  536. underline](#setext-header-underline). The line of text must be
  537. one that, were it not followed by the setext header underline,
  538. would be interpreted as part of a paragraph: it cannot be a code
  539. block, header, blockquote, horizontal rule, or list. A [setext header
  540. underline](#setext-header-underline) <a id="setext-header-underline"></a>
  541. is a sequence of `=` characters or a sequence of `-` characters, with no
  542. more than 3 spaces indentation and any number of trailing
  543. spaces. The header is a level 1 header if `=` characters are used, and
  544. a level 2 header if `-` characters are used. The contents of the header
  545. are the result of parsing the first line as Markdown inline content.
  546. In general, a setext header need not be preceded or followed by a
  547. blank line. However, it cannot interrupt a paragraph, so when a
  548. setext header comes after a paragraph, a blank line is needed between
  549. them.
  550. Simple examples:
  551. .
  552. Foo *bar*
  553. =========
  554. Foo *bar*
  555. ---------
  556. .
  557. <h1>Foo <em>bar</em></h1>
  558. <h2>Foo <em>bar</em></h2>
  559. .
  560. The underlining can be any length:
  561. .
  562. Foo
  563. -------------------------
  564. Foo
  565. =
  566. .
  567. <h2>Foo</h2>
  568. <h1>Foo</h1>
  569. .
  570. The header content can be indented up to three spaces, and need
  571. not line up with the underlining:
  572. .
  573. Foo
  574. ---
  575. Foo
  576. -----
  577. Foo
  578. ===
  579. .
  580. <h2>Foo</h2>
  581. <h2>Foo</h2>
  582. <h1>Foo</h1>
  583. .
  584. Four spaces indent is too much:
  585. .
  586. Foo
  587. ---
  588. Foo
  589. ---
  590. .
  591. <pre><code>Foo
  592. ---
  593. Foo
  594. </code></pre>
  595. <hr />
  596. .
  597. The setext header underline can be indented up to three spaces, and
  598. may have trailing spaces:
  599. .
  600. Foo
  601. ----
  602. .
  603. <h2>Foo</h2>
  604. .
  605. Four spaces is too much:
  606. .
  607. Foo
  608. ---
  609. .
  610. <p>Foo
  611. ---</p>
  612. .
  613. The setext header underline cannot contain internal spaces:
  614. .
  615. Foo
  616. = =
  617. Foo
  618. --- -
  619. .
  620. <p>Foo
  621. = =</p>
  622. <p>Foo</p>
  623. <hr />
  624. .
  625. Trailing spaces in the content line do not cause a line break:
  626. .
  627. Foo
  628. -----
  629. .
  630. <h2>Foo</h2>
  631. .
  632. Nor does a backslash at the end:
  633. .
  634. Foo\
  635. ----
  636. .
  637. <h2>Foo\</h2>
  638. .
  639. Since indicators of block structure take precedence over
  640. indicators of inline structure, the following are setext headers:
  641. .
  642. `Foo
  643. ----
  644. `
  645. <a title="a lot
  646. ---
  647. of dashes"/>
  648. .
  649. <h2>`Foo</h2>
  650. <p>`</p>
  651. <h2>&lt;a title=&quot;a lot</h2>
  652. <p>of dashes&quot;/&gt;</p>
  653. .
  654. The setext header underline cannot be a [lazy continuation
  655. line](#lazy-continuation-line) in a list item or block quote:
  656. .
  657. > Foo
  658. ---
  659. .
  660. <blockquote>
  661. <p>Foo</p>
  662. </blockquote>
  663. <hr />
  664. .
  665. .
  666. - Foo
  667. ---
  668. .
  669. <ul>
  670. <li>Foo</li>
  671. </ul>
  672. <hr />
  673. .
  674. A setext header cannot interrupt a paragraph:
  675. .
  676. Foo
  677. Bar
  678. ---
  679. Foo
  680. Bar
  681. ===
  682. .
  683. <p>Foo
  684. Bar</p>
  685. <hr />
  686. <p>Foo
  687. Bar
  688. ===</p>
  689. .
  690. But in general a blank line is not required before or after:
  691. .
  692. ---
  693. Foo
  694. ---
  695. Bar
  696. ---
  697. Baz
  698. .
  699. <hr />
  700. <h2>Foo</h2>
  701. <h2>Bar</h2>
  702. <p>Baz</p>
  703. .
  704. Setext headers cannot be empty:
  705. .
  706. ====
  707. .
  708. <p>====</p>
  709. .
  710. Setext header text lines must not be interpretable as block
  711. constructs other than paragraphs. So, the line of dashes
  712. in these examples gets interpreted as a horizontal rule:
  713. .
  714. ---
  715. ---
  716. .
  717. <hr />
  718. <hr />
  719. .
  720. .
  721. - foo
  722. -----
  723. .
  724. <ul>
  725. <li>foo</li>
  726. </ul>
  727. <hr />
  728. .
  729. .
  730. foo
  731. ---
  732. .
  733. <pre><code>foo
  734. </code></pre>
  735. <hr />
  736. .
  737. .
  738. > foo
  739. -----
  740. .
  741. <blockquote>
  742. <p>foo</p>
  743. </blockquote>
  744. <hr />
  745. .
  746. If you want a header with `> foo` as its literal text, you can
  747. use backslash escapes:
  748. .
  749. \> foo
  750. ------
  751. .
  752. <h2>&gt; foo</h2>
  753. .
  754. ## Indented code blocks
  755. An [indented code block](#indented-code-block)
  756. <a id="indented-code-block"></a> is composed of one or more
  757. [indented chunks](#indented-chunk) separated by blank lines.
  758. An [indented chunk](#indented-chunk) <a id="indented-chunk"></a>
  759. is a sequence of non-blank lines, each indented four or more
  760. spaces. An indented code block cannot interrupt a paragraph, so
  761. if it occurs before or after a paragraph, there must be an
  762. intervening blank line. The contents of the code block are
  763. the literal contents of the lines, including trailing newlines,
  764. minus four spaces of indentation. An indented code block has no
  765. attributes.
  766. .
  767. a simple
  768. indented code block
  769. .
  770. <pre><code>a simple
  771. indented code block
  772. </code></pre>
  773. .
  774. The contents are literal text, and do not get parsed as Markdown:
  775. .
  776. <a/>
  777. *hi*
  778. - one
  779. .
  780. <pre><code>&lt;a/&gt;
  781. *hi*
  782. - one
  783. </code></pre>
  784. .
  785. Here we have three chunks separated by blank lines:
  786. .
  787. chunk1
  788. chunk2
  789. chunk3
  790. .
  791. <pre><code>chunk1
  792. chunk2
  793. chunk3
  794. </code></pre>
  795. .
  796. Any initial spaces beyond four will be included in the content, even
  797. in interior blank lines:
  798. .
  799. chunk1
  800. chunk2
  801. .
  802. <pre><code>chunk1
  803. chunk2
  804. </code></pre>
  805. .
  806. An indented code block cannot interrupt a paragraph. (This
  807. allows hanging indents and the like.)
  808. .
  809. Foo
  810. bar
  811. .
  812. <p>Foo
  813. bar</p>
  814. .
  815. However, any non-blank line with fewer than four leading spaces ends
  816. the code block immediately. So a paragraph may occur immediately
  817. after indented code:
  818. .
  819. foo
  820. bar
  821. .
  822. <pre><code>foo
  823. </code></pre>
  824. <p>bar</p>
  825. .
  826. And indented code can occur immediately before and after other kinds of
  827. blocks:
  828. .
  829. # Header
  830. foo
  831. Header
  832. ------
  833. foo
  834. ----
  835. .
  836. <h1>Header</h1>
  837. <pre><code>foo
  838. </code></pre>
  839. <h2>Header</h2>
  840. <pre><code>foo
  841. </code></pre>
  842. <hr />
  843. .
  844. The first line can be indented more than four spaces:
  845. .
  846. foo
  847. bar
  848. .
  849. <pre><code> foo
  850. bar
  851. </code></pre>
  852. .
  853. Blank lines preceding or following an indented code block
  854. are not included in it:
  855. .
  856. foo
  857. .
  858. <pre><code>foo
  859. </code></pre>
  860. .
  861. Trailing spaces are included in the code block's content:
  862. .
  863. foo
  864. .
  865. <pre><code>foo
  866. </code></pre>
  867. .
  868. ## Fenced code blocks
  869. A [code fence](#code-fence) <a id="code-fence"></a> is a sequence
  870. of at least three consecutive backtick characters (`` ` ``) or
  871. tildes (`~`). (Tildes and backticks cannot be mixed.)
  872. A [fenced code block](#fenced-code-block) <a id="fenced-code-block"></a>
  873. begins with a code fence, indented no more than three spaces.
  874. The line with the opening code fence may optionally contain some text
  875. following the code fence; this is trimmed of leading and trailing
  876. spaces and called the [info string](#info-string).
  877. <a id="info-string"></a> The info string may not contain any backtick
  878. characters. (The reason for this restriction is that otherwise
  879. some inline code would be incorrectly interpreted as the
  880. beginning of a fenced code block.)
  881. The content of the code block consists of all subsequent lines, until
  882. a closing [code fence](#code-fence) of the same type as the code block
  883. began with (backticks or tildes), and with at least as many backticks
  884. or tildes as the opening code fence. If the leading code fence is
  885. indented N spaces, then up to N spaces of indentation are removed from
  886. each line of the content (if present). (If a content line is not
  887. indented, it is preserved unchanged. If it is indented less than N
  888. spaces, all of the indentation is removed.)
  889. The closing code fence may be indented up to three spaces, and may be
  890. followed only by spaces, which are ignored. If the end of the
  891. containing block (or document) is reached and no closing code fence
  892. has been found, the code block contains all of the lines after the
  893. opening code fence until the end of the containing block (or
  894. document). (An alternative spec would require backtracking in the
  895. event that a closing code fence is not found. But this makes parsing
  896. much less efficient, and there seems to be no real down side to the
  897. behavior described here.)
  898. A fenced code block may interrupt a paragraph, and does not require
  899. a blank line either before or after.
  900. The content of a code fence is treated as literal text, not parsed
  901. as inlines. The first word of the info string is typically used to
  902. specify the language of the code sample, and rendered in the `class`
  903. attribute of the `code` tag. However, this spec does not mandate any
  904. particular treatment of the info string.
  905. Here is a simple example with backticks:
  906. .
  907. ```
  908. <
  909. >
  910. ```
  911. .
  912. <pre><code>&lt;
  913. &gt;
  914. </code></pre>
  915. .
  916. With tildes:
  917. .
  918. ~~~
  919. <
  920. >
  921. ~~~
  922. .
  923. <pre><code>&lt;
  924. &gt;
  925. </code></pre>
  926. .
  927. The closing code fence must use the same character as the opening
  928. fence:
  929. .
  930. ```
  931. aaa
  932. ~~~
  933. ```
  934. .
  935. <pre><code>aaa
  936. ~~~
  937. </code></pre>
  938. .
  939. .
  940. ~~~
  941. aaa
  942. ```
  943. ~~~
  944. .
  945. <pre><code>aaa
  946. ```
  947. </code></pre>
  948. .
  949. The closing code fence must be at least as long as the opening fence:
  950. .
  951. ````
  952. aaa
  953. ```
  954. ``````
  955. .
  956. <pre><code>aaa
  957. ```
  958. </code></pre>
  959. .
  960. .
  961. ~~~~
  962. aaa
  963. ~~~
  964. ~~~~
  965. .
  966. <pre><code>aaa
  967. ~~~
  968. </code></pre>
  969. .
  970. Unclosed code blocks are closed by the end of the document:
  971. .
  972. ```
  973. .
  974. <pre><code></code></pre>
  975. .
  976. .
  977. `````
  978. ```
  979. aaa
  980. .
  981. <pre><code>
  982. ```
  983. aaa
  984. </code></pre>
  985. .
  986. A code block can have all empty lines as its content:
  987. .
  988. ```
  989. ```
  990. .
  991. <pre><code>
  992. </code></pre>
  993. .
  994. A code block can be empty:
  995. .
  996. ```
  997. ```
  998. .
  999. <pre><code></code></pre>
  1000. .
  1001. Fences can be indented. If the opening fence is indented,
  1002. content lines will have equivalent opening indentation removed,
  1003. if present:
  1004. .
  1005. ```
  1006. aaa
  1007. aaa
  1008. ```
  1009. .
  1010. <pre><code>aaa
  1011. aaa
  1012. </code></pre>
  1013. .
  1014. .
  1015. ```
  1016. aaa
  1017. aaa
  1018. aaa
  1019. ```
  1020. .
  1021. <pre><code>aaa
  1022. aaa
  1023. aaa
  1024. </code></pre>
  1025. .
  1026. .
  1027. ```
  1028. aaa
  1029. aaa
  1030. aaa
  1031. ```
  1032. .
  1033. <pre><code>aaa
  1034. aaa
  1035. aaa
  1036. </code></pre>
  1037. .
  1038. Four spaces indentation produces an indented code block:
  1039. .
  1040. ```
  1041. aaa
  1042. ```
  1043. .
  1044. <pre><code>```
  1045. aaa
  1046. ```
  1047. </code></pre>
  1048. .
  1049. Code fences (opening and closing) cannot contain internal spaces:
  1050. .
  1051. ``` ```
  1052. aaa
  1053. .
  1054. <p><code></code>
  1055. aaa</p>
  1056. .
  1057. .
  1058. ~~~~~~
  1059. aaa
  1060. ~~~ ~~
  1061. .
  1062. <pre><code>aaa
  1063. ~~~ ~~
  1064. </code></pre>
  1065. .
  1066. Fenced code blocks can interrupt paragraphs, and can be followed
  1067. directly by paragraphs, without a blank line between:
  1068. .
  1069. foo
  1070. ```
  1071. bar
  1072. ```
  1073. baz
  1074. .
  1075. <p>foo</p>
  1076. <pre><code>bar
  1077. </code></pre>
  1078. <p>baz</p>
  1079. .
  1080. Other blocks can also occur before and after fenced code blocks
  1081. without an intervening blank line:
  1082. .
  1083. foo
  1084. ---
  1085. ~~~
  1086. bar
  1087. ~~~
  1088. # baz
  1089. .
  1090. <h2>foo</h2>
  1091. <pre><code>bar
  1092. </code></pre>
  1093. <h1>baz</h1>
  1094. .
  1095. An [info string](#info-string) can be provided after the opening code fence.
  1096. Opening and closing spaces will be stripped, and the first word, prefixed
  1097. with `language-`, is used as the value for the `class` attribute of the
  1098. `code` element within the enclosing `pre` element.
  1099. .
  1100. ```ruby
  1101. def foo(x)
  1102. return 3
  1103. end
  1104. ```
  1105. .
  1106. <pre><code class="language-ruby">def foo(x)
  1107. return 3
  1108. end
  1109. </code></pre>
  1110. .
  1111. .
  1112. ~~~~ ruby startline=3 $%@#$
  1113. def foo(x)
  1114. return 3
  1115. end
  1116. ~~~~~~~
  1117. .
  1118. <pre><code class="language-ruby">def foo(x)
  1119. return 3
  1120. end
  1121. </code></pre>
  1122. .
  1123. .
  1124. ````;
  1125. ````
  1126. .
  1127. <pre><code class="language-;"></code></pre>
  1128. .
  1129. Info strings for backtick code blocks cannot contain backticks:
  1130. .
  1131. ``` aa ```
  1132. foo
  1133. .
  1134. <p><code>aa</code>
  1135. foo</p>
  1136. .
  1137. Closing code fences cannot have info strings:
  1138. .
  1139. ```
  1140. ``` aaa
  1141. ```
  1142. .
  1143. <pre><code>``` aaa
  1144. </code></pre>
  1145. .
  1146. ## HTML blocks
  1147. An [HTML block tag](#html-block-tag) <a id="html-block-tag"></a> is
  1148. an [open tag](#open-tag) or [closing tag](#closing-tag) whose tag
  1149. name is one of the following (case-insensitive):
  1150. `article`, `header`, `aside`, `hgroup`, `blockquote`, `hr`, `iframe`,
  1151. `body`, `li`, `map`, `button`, `object`, `canvas`, `ol`, `caption`,
  1152. `output`, `col`, `p`, `colgroup`, `pre`, `dd`, `progress`, `div`,
  1153. `section`, `dl`, `table`, `td`, `dt`, `tbody`, `embed`, `textarea`,
  1154. `fieldset`, `tfoot`, `figcaption`, `th`, `figure`, `thead`, `footer`,
  1155. `tr`, `form`, `ul`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `video`,
  1156. `script`, `style`.
  1157. An [HTML block](#html-block) <a id="html-block"></a> begins with an
  1158. [HTML block tag](#html-block-tag), [HTML comment](#html-comment),
  1159. [processing instruction](#processing-instruction),
  1160. [declaration](#declaration), or [CDATA section](#cdata-section).
  1161. It ends when a [blank line](#blank-line) or the end of the
  1162. input is encountered. The initial line may be indented up to three
  1163. spaces, and subsequent lines may have any indentation. The contents
  1164. of the HTML block are interpreted as raw HTML, and will not be escaped
  1165. in HTML output.
  1166. Some simple examples:
  1167. .
  1168. <table>
  1169. <tr>
  1170. <td>
  1171. hi
  1172. </td>
  1173. </tr>
  1174. </table>
  1175. okay.
  1176. .
  1177. <table>
  1178. <tr>
  1179. <td>
  1180. hi
  1181. </td>
  1182. </tr>
  1183. </table>
  1184. <p>okay.</p>
  1185. .
  1186. .
  1187. <div>
  1188. *hello*
  1189. <foo><a>
  1190. .
  1191. <div>
  1192. *hello*
  1193. <foo><a>
  1194. .
  1195. Here we have two HTML blocks with a Markdown paragraph between them:
  1196. .
  1197. <DIV CLASS="foo">
  1198. *Markdown*
  1199. </DIV>
  1200. .
  1201. <DIV CLASS="foo">
  1202. <p><em>Markdown</em></p>
  1203. </DIV>
  1204. .
  1205. In the following example, what looks like a Markdown code block
  1206. is actually part of the HTML block, which continues until a blank
  1207. line or the end of the document is reached:
  1208. .
  1209. <div></div>
  1210. ``` c
  1211. int x = 33;
  1212. ```
  1213. .
  1214. <div></div>
  1215. ``` c
  1216. int x = 33;
  1217. ```
  1218. .
  1219. A comment:
  1220. .
  1221. <!-- Foo
  1222. bar
  1223. baz -->
  1224. .
  1225. <!-- Foo
  1226. bar
  1227. baz -->
  1228. .
  1229. A processing instruction:
  1230. .
  1231. <?php
  1232. echo '>';
  1233. ?>
  1234. .
  1235. <?php
  1236. echo '>';
  1237. ?>
  1238. .
  1239. CDATA:
  1240. .
  1241. <![CDATA[
  1242. function matchwo(a,b)
  1243. {
  1244. if (a < b && a < 0) then
  1245. {
  1246. return 1;
  1247. }
  1248. else
  1249. {
  1250. return 0;
  1251. }
  1252. }
  1253. ]]>
  1254. .
  1255. <![CDATA[
  1256. function matchwo(a,b)
  1257. {
  1258. if (a < b && a < 0) then
  1259. {
  1260. return 1;
  1261. }
  1262. else
  1263. {
  1264. return 0;
  1265. }
  1266. }
  1267. ]]>
  1268. .
  1269. The opening tag can be indented 1-3 spaces, but not 4:
  1270. .
  1271. <!-- foo -->
  1272. <!-- foo -->
  1273. .
  1274. <!-- foo -->
  1275. <pre><code>&lt;!-- foo --&gt;
  1276. </code></pre>
  1277. .
  1278. An HTML block can interrupt a paragraph, and need not be preceded
  1279. by a blank line.
  1280. .
  1281. Foo
  1282. <div>
  1283. bar
  1284. </div>
  1285. .
  1286. <p>Foo</p>
  1287. <div>
  1288. bar
  1289. </div>
  1290. .
  1291. However, a following blank line is always needed, except at the end of
  1292. a document:
  1293. .
  1294. <div>
  1295. bar
  1296. </div>
  1297. *foo*
  1298. .
  1299. <div>
  1300. bar
  1301. </div>
  1302. *foo*
  1303. .
  1304. An incomplete HTML block tag may also start an HTML block:
  1305. .
  1306. <div class
  1307. foo
  1308. .
  1309. <div class
  1310. foo
  1311. .
  1312. This rule differs from John Gruber's original Markdown syntax
  1313. specification, which says:
  1314. > The only restrictions are that block-level HTML elements —
  1315. > e.g. `<div>`, `<table>`, `<pre>`, `<p>`, etc. — must be separated from
  1316. > surrounding content by blank lines, and the start and end tags of the
  1317. > block should not be indented with tabs or spaces.
  1318. In some ways Gruber's rule is more restrictive than the one given
  1319. here:
  1320. - It requires that an HTML block be preceded by a blank line.
  1321. - It does not allow the start tag to be indented.
  1322. - It requires a matching end tag, which it also does not allow to
  1323. be indented.
  1324. Indeed, most Markdown implementations, including some of Gruber's
  1325. own perl implementations, do not impose these restrictions.
  1326. There is one respect, however, in which Gruber's rule is more liberal
  1327. than the one given here, since it allows blank lines to occur inside
  1328. an HTML block. There are two reasons for disallowing them here.
  1329. First, it removes the need to parse balanced tags, which is
  1330. expensive and can require backtracking from the end of the document
  1331. if no matching end tag is found. Second, it provides a very simple
  1332. and flexible way of including Markdown content inside HTML tags:
  1333. simply separate the Markdown from the HTML using blank lines:
  1334. .
  1335. <div>
  1336. *Emphasized* text.
  1337. </div>
  1338. .
  1339. <div>
  1340. <p><em>Emphasized</em> text.</p>
  1341. </div>
  1342. .
  1343. Compare:
  1344. .
  1345. <div>
  1346. *Emphasized* text.
  1347. </div>
  1348. .
  1349. <div>
  1350. *Emphasized* text.
  1351. </div>
  1352. .
  1353. Some Markdown implementations have adopted a convention of
  1354. interpreting content inside tags as text if the open tag has
  1355. the attribute `markdown=1`. The rule given above seems a simpler and
  1356. more elegant way of achieving the same expressive power, which is also
  1357. much simpler to parse.
  1358. The main potential drawback is that one can no longer paste HTML
  1359. blocks into Markdown documents with 100% reliability. However,
  1360. *in most cases* this will work fine, because the blank lines in
  1361. HTML are usually followed by HTML block tags. For example:
  1362. .
  1363. <table>
  1364. <tr>
  1365. <td>
  1366. Hi
  1367. </td>
  1368. </tr>
  1369. </table>
  1370. .
  1371. <table>
  1372. <tr>
  1373. <td>
  1374. Hi
  1375. </td>
  1376. </tr>
  1377. </table>
  1378. .
  1379. Moreover, blank lines are usually not necessary and can be
  1380. deleted. The exception is inside `<pre>` tags; here, one can
  1381. replace the blank lines with `&#10;` entities.
  1382. So there is no important loss of expressive power with the new rule.
  1383. ## Link reference definitions
  1384. A [link reference definition](#link-reference-definition)
  1385. <a id="link-reference-definition"></a> consists of a [link
  1386. label](#link-label), indented up to three spaces, followed
  1387. by a colon (`:`), optional blank space (including up to one
  1388. newline), a [link destination](#link-destination), optional
  1389. blank space (including up to one newline), and an optional [link
  1390. title](#link-title), which if it is present must be separated
  1391. from the [link destination](#link-destination) by whitespace.
  1392. No further non-space characters may occur on the line.
  1393. A [link reference-definition](#link-reference-definition)
  1394. does not correspond to a structural element of a document. Instead, it
  1395. defines a label which can be used in [reference links](#reference-link)
  1396. and reference-style [images](#image) elsewhere in the document. [Link
  1397. reference definitions] can come either before or after the links that use
  1398. them.
  1399. .
  1400. [foo]: /url "title"
  1401. [foo]
  1402. .
  1403. <p><a href="/url" title="title">foo</a></p>
  1404. .
  1405. .
  1406. [foo]:
  1407. /url
  1408. 'the title'
  1409. [foo]
  1410. .
  1411. <p><a href="/url" title="the title">foo</a></p>
  1412. .
  1413. .
  1414. [Foo*bar\]]:my_(url) 'title (with parens)'
  1415. [Foo*bar\]]
  1416. .
  1417. <p><a href="my_(url)" title="title (with parens)">Foo*bar]</a></p>
  1418. .
  1419. .
  1420. [Foo bar]:
  1421. <my url>
  1422. 'title'
  1423. [Foo bar]
  1424. .
  1425. <p><a href="my%20url" title="title">Foo bar</a></p>
  1426. .
  1427. The title may be omitted:
  1428. .
  1429. [foo]:
  1430. /url
  1431. [foo]
  1432. .
  1433. <p><a href="/url">foo</a></p>
  1434. .
  1435. The link destination may not be omitted:
  1436. .
  1437. [foo]:
  1438. [foo]
  1439. .
  1440. <p>[foo]:</p>
  1441. <p>[foo]</p>
  1442. .
  1443. A link can come before its corresponding definition:
  1444. .
  1445. [foo]
  1446. [foo]: url
  1447. .
  1448. <p><a href="url">foo</a></p>
  1449. .
  1450. If there are several matching definitions, the first one takes
  1451. precedence:
  1452. .
  1453. [foo]
  1454. [foo]: first
  1455. [foo]: second
  1456. .
  1457. <p><a href="first">foo</a></p>
  1458. .
  1459. As noted in the section on [Links], matching of labels is
  1460. case-insensitive (see [matches](#matches)).
  1461. .
  1462. [FOO]: /url
  1463. [Foo]
  1464. .
  1465. <p><a href="/url">Foo</a></p>
  1466. .
  1467. .
  1468. [ΑΓΩ]: /φου
  1469. [αγω]
  1470. .
  1471. <p><a href="/%CF%86%CE%BF%CF%85">αγω</a></p>
  1472. .
  1473. Here is a link reference definition with no corresponding link.
  1474. It contributes nothing to the document.
  1475. .
  1476. [foo]: /url
  1477. .
  1478. .
  1479. This is not a link reference definition, because there are
  1480. non-space characters after the title:
  1481. .
  1482. [foo]: /url "title" ok
  1483. .
  1484. <p>[foo]: /url &quot;title&quot; ok</p>
  1485. .
  1486. This is not a link reference definition, because it is indented
  1487. four spaces:
  1488. .
  1489. [foo]: /url "title"
  1490. [foo]
  1491. .
  1492. <pre><code>[foo]: /url &quot;title&quot;
  1493. </code></pre>
  1494. <p>[foo]</p>
  1495. .
  1496. This is not a link reference definition, because it occurs inside
  1497. a code block:
  1498. .
  1499. ```
  1500. [foo]: /url
  1501. ```
  1502. [foo]
  1503. .
  1504. <pre><code>[foo]: /url
  1505. </code></pre>
  1506. <p>[foo]</p>
  1507. .
  1508. A [link reference definition](#link-reference-definition) cannot
  1509. interrupt a paragraph.
  1510. .
  1511. Foo
  1512. [bar]: /baz
  1513. [bar]
  1514. .
  1515. <p>Foo
  1516. [bar]: /baz</p>
  1517. <p>[bar]</p>
  1518. .
  1519. However, it can directly follow other block elements, such as headers
  1520. and horizontal rules, and it need not be followed by a blank line.
  1521. .
  1522. # [Foo]
  1523. [foo]: /url
  1524. > bar
  1525. .
  1526. <h1><a href="/url">Foo</a></h1>
  1527. <blockquote>
  1528. <p>bar</p>
  1529. </blockquote>
  1530. .
  1531. Several [link references](#link-reference) can occur one after another,
  1532. without intervening blank lines.
  1533. .
  1534. [foo]: /foo-url "foo"
  1535. [bar]: /bar-url
  1536. "bar"
  1537. [baz]: /baz-url
  1538. [foo],
  1539. [bar],
  1540. [baz]
  1541. .
  1542. <p><a href="/foo-url" title="foo">foo</a>,
  1543. <a href="/bar-url" title="bar">bar</a>,
  1544. <a href="/baz-url">baz</a></p>
  1545. .
  1546. [Link reference definitions](#link-reference-definition) can occur
  1547. inside block containers, like lists and block quotations. They
  1548. affect the entire document, not just the container in which they
  1549. are defined:
  1550. .
  1551. [foo]
  1552. > [foo]: /url
  1553. .
  1554. <p><a href="/url">foo</a></p>
  1555. <blockquote>
  1556. </blockquote>
  1557. .
  1558. ## Paragraphs
  1559. A sequence of non-blank lines that cannot be interpreted as other
  1560. kinds of blocks forms a [paragraph](#paragraph).<a id="paragraph"></a>
  1561. The contents of the paragraph are the result of parsing the
  1562. paragraph's raw content as inlines. The paragraph's raw content
  1563. is formed by concatenating the lines and removing initial and final
  1564. spaces.
  1565. A simple example with two paragraphs:
  1566. .
  1567. aaa
  1568. bbb
  1569. .
  1570. <p>aaa</p>
  1571. <p>bbb</p>
  1572. .
  1573. Paragraphs can contain multiple lines, but no blank lines:
  1574. .
  1575. aaa
  1576. bbb
  1577. ccc
  1578. ddd
  1579. .
  1580. <p>aaa
  1581. bbb</p>
  1582. <p>ccc
  1583. ddd</p>
  1584. .
  1585. Multiple blank lines between paragraph have no effect:
  1586. .
  1587. aaa
  1588. bbb
  1589. .
  1590. <p>aaa</p>
  1591. <p>bbb</p>
  1592. .
  1593. Leading spaces are skipped:
  1594. .
  1595. aaa
  1596. bbb
  1597. .
  1598. <p>aaa
  1599. bbb</p>
  1600. .
  1601. Lines after the first may be indented any amount, since indented
  1602. code blocks cannot interrupt paragraphs.
  1603. .
  1604. aaa
  1605. bbb
  1606. ccc
  1607. .
  1608. <p>aaa
  1609. bbb
  1610. ccc</p>
  1611. .
  1612. However, the first line may be indented at most three spaces,
  1613. or an indented code block will be triggered:
  1614. .
  1615. aaa
  1616. bbb
  1617. .
  1618. <p>aaa
  1619. bbb</p>
  1620. .
  1621. .
  1622. aaa
  1623. bbb
  1624. .
  1625. <pre><code>aaa
  1626. </code></pre>
  1627. <p>bbb</p>
  1628. .
  1629. Final spaces are stripped before inline parsing, so a paragraph
  1630. that ends with two or more spaces will not end with a [hard line
  1631. break](#hard-line-break):
  1632. .
  1633. aaa
  1634. bbb
  1635. .
  1636. <p>aaa<br />
  1637. bbb</p>
  1638. .
  1639. ## Blank lines
  1640. [Blank lines](#blank-line) between block-level elements are ignored,
  1641. except for the role they play in determining whether a [list](#list)
  1642. is [tight](#tight) or [loose](#loose).
  1643. Blank lines at the beginning and end of the document are also ignored.
  1644. .
  1645. aaa
  1646. # aaa
  1647. .
  1648. <p>aaa</p>
  1649. <h1>aaa</h1>
  1650. .
  1651. # Container blocks
  1652. A [container block](#container-block) is a block that has other
  1653. blocks as its contents. There are two basic kinds of container blocks:
  1654. [block quotes](#block-quote) and [list items](#list-item).
  1655. [Lists](#list) are meta-containers for [list items](#list-item).
  1656. We define the syntax for container blocks recursively. The general
  1657. form of the definition is:
  1658. > If X is a sequence of blocks, then the result of
  1659. > transforming X in such-and-such a way is a container of type Y
  1660. > with these blocks as its content.
  1661. So, we explain what counts as a block quote or list item by explaining
  1662. how these can be *generated* from their contents. This should suffice
  1663. to define the syntax, although it does not give a recipe for *parsing*
  1664. these constructions. (A recipe is provided below in the section entitled
  1665. [A parsing strategy](#appendix-a-a-parsing-strategy).)
  1666. ## Block quotes
  1667. A [block quote marker](#block-quote-marker) <a id="block-quote-marker"></a>
  1668. consists of 0-3 spaces of initial indent, plus (a) the character `>` together
  1669. with a following space, or (b) a single character `>` not followed by a space.
  1670. The following rules define [block quotes](#block-quote):
  1671. <a id="block-quote"></a>
  1672. 1. **Basic case.** If a string of lines *Ls* constitute a sequence
  1673. of blocks *Bs*, then the result of prepending a [block quote
  1674. marker](#block-quote-marker) to the beginning of each line in *Ls*
  1675. is a [block quote](#block-quote) containing *Bs*.
  1676. 2. **Laziness.** If a string of lines *Ls* constitute a [block
  1677. quote](#block-quote) with contents *Bs*, then the result of deleting
  1678. the initial [block quote marker](#block-quote-marker) from one or
  1679. more lines in which the next non-space character after the [block
  1680. quote marker](#block-quote-marker) is [paragraph continuation
  1681. text](#paragraph-continuation-text) is a block quote with *Bs* as
  1682. its content. <a id="paragraph-continuation-text"></a>
  1683. [Paragraph continuation text](#paragraph-continuation-text) is text
  1684. that will be parsed as part of the content of a paragraph, but does
  1685. not occur at the beginning of the paragraph.
  1686. 3. **Consecutiveness.** A document cannot contain two [block
  1687. quotes](#block-quote) in a row unless there is a [blank
  1688. line](#blank-line) between them.
  1689. Nothing else counts as a [block quote](#block-quote).
  1690. Here is a simple example:
  1691. .
  1692. > # Foo
  1693. > bar
  1694. > baz
  1695. .
  1696. <blockquote>
  1697. <h1>Foo</h1>
  1698. <p>bar
  1699. baz</p>
  1700. </blockquote>
  1701. .
  1702. The spaces after the `>` characters can be omitted:
  1703. .
  1704. ># Foo
  1705. >bar
  1706. > baz
  1707. .
  1708. <blockquote>
  1709. <h1>Foo</h1>
  1710. <p>bar
  1711. baz</p>
  1712. </blockquote>
  1713. .
  1714. The `>` characters can be indented 1-3 spaces:
  1715. .
  1716. > # Foo
  1717. > bar
  1718. > baz
  1719. .
  1720. <blockquote>
  1721. <h1>Foo</h1>
  1722. <p>bar
  1723. baz</p>
  1724. </blockquote>
  1725. .
  1726. Four spaces gives us a code block:
  1727. .
  1728. > # Foo
  1729. > bar
  1730. > baz
  1731. .
  1732. <pre><code>&gt; # Foo
  1733. &gt; bar
  1734. &gt; baz
  1735. </code></pre>
  1736. .
  1737. The Laziness clause allows us to omit the `>` before a
  1738. paragraph continuation line:
  1739. .
  1740. > # Foo
  1741. > bar
  1742. baz
  1743. .
  1744. <blockquote>
  1745. <h1>Foo</h1>
  1746. <p>bar
  1747. baz</p>
  1748. </blockquote>
  1749. .
  1750. A block quote can contain some lazy and some non-lazy
  1751. continuation lines:
  1752. .
  1753. > bar
  1754. baz
  1755. > foo
  1756. .
  1757. <blockquote>
  1758. <p>bar
  1759. baz
  1760. foo</p>
  1761. </blockquote>
  1762. .
  1763. Laziness only applies to lines that are continuations of
  1764. paragraphs. Lines containing characters or indentation that indicate
  1765. block structure cannot be lazy.
  1766. .
  1767. > foo
  1768. ---
  1769. .
  1770. <blockquote>
  1771. <p>foo</p>
  1772. </blockquote>
  1773. <hr />
  1774. .
  1775. .
  1776. > - foo
  1777. - bar
  1778. .
  1779. <blockquote>
  1780. <ul>
  1781. <li>foo</li>
  1782. </ul>
  1783. </blockquote>
  1784. <ul>
  1785. <li>bar</li>
  1786. </ul>
  1787. .
  1788. .
  1789. > foo
  1790. bar
  1791. .
  1792. <blockquote>
  1793. <pre><code>foo
  1794. </code></pre>
  1795. </blockquote>
  1796. <pre><code>bar
  1797. </code></pre>
  1798. .
  1799. .
  1800. > ```
  1801. foo
  1802. ```
  1803. .
  1804. <blockquote>
  1805. <pre><code></code></pre>
  1806. </blockquote>
  1807. <p>foo</p>
  1808. <pre><code></code></pre>
  1809. .
  1810. A block quote can be empty:
  1811. .
  1812. >
  1813. .
  1814. <blockquote>
  1815. </blockquote>
  1816. .
  1817. .
  1818. >
  1819. >
  1820. >
  1821. .
  1822. <blockquote>
  1823. </blockquote>
  1824. .
  1825. A block quote can have initial or final blank lines:
  1826. .
  1827. >
  1828. > foo
  1829. >
  1830. .
  1831. <blockquote>
  1832. <p>foo</p>
  1833. </blockquote>
  1834. .
  1835. A blank line always separates block quotes:
  1836. .
  1837. > foo
  1838. > bar
  1839. .
  1840. <blockquote>
  1841. <p>foo</p>
  1842. </blockquote>
  1843. <blockquote>
  1844. <p>bar</p>
  1845. </blockquote>
  1846. .
  1847. (Most current Markdown implementations, including John Gruber's
  1848. original `Markdown.pl`, will parse this example as a single block quote
  1849. with two paragraphs. But it seems better to allow the author to decide
  1850. whether two block quotes or one are wanted.)
  1851. Consecutiveness means that if we put these block quotes together,
  1852. we get a single block quote:
  1853. .
  1854. > foo
  1855. > bar
  1856. .
  1857. <blockquote>
  1858. <p>foo
  1859. bar</p>
  1860. </blockquote>
  1861. .
  1862. To get a block quote with two paragraphs, use:
  1863. .
  1864. > foo
  1865. >
  1866. > bar
  1867. .
  1868. <blockquote>
  1869. <p>foo</p>
  1870. <p>bar</p>
  1871. </blockquote>
  1872. .
  1873. Block quotes can interrupt paragraphs:
  1874. .
  1875. foo
  1876. > bar
  1877. .
  1878. <p>foo</p>
  1879. <blockquote>
  1880. <p>bar</p>
  1881. </blockquote>
  1882. .
  1883. In general, blank lines are not needed before or after block
  1884. quotes:
  1885. .
  1886. > aaa
  1887. ***
  1888. > bbb
  1889. .
  1890. <blockquote>
  1891. <p>aaa</p>
  1892. </blockquote>
  1893. <hr />
  1894. <blockquote>
  1895. <p>bbb</p>
  1896. </blockquote>
  1897. .
  1898. However, because of laziness, a blank line is needed between
  1899. a block quote and a following paragraph:
  1900. .
  1901. > bar
  1902. baz
  1903. .
  1904. <blockquote>
  1905. <p>bar
  1906. baz</p>
  1907. </blockquote>
  1908. .
  1909. .
  1910. > bar
  1911. baz
  1912. .
  1913. <blockquote>
  1914. <p>bar</p>
  1915. </blockquote>
  1916. <p>baz</p>
  1917. .
  1918. .
  1919. > bar
  1920. >
  1921. baz
  1922. .
  1923. <blockquote>
  1924. <p>bar</p>
  1925. </blockquote>
  1926. <p>baz</p>
  1927. .
  1928. It is a consequence of the Laziness rule that any number
  1929. of initial `>`s may be omitted on a continuation line of a
  1930. nested block quote:
  1931. .
  1932. > > > foo
  1933. bar
  1934. .
  1935. <blockquote>
  1936. <blockquote>
  1937. <blockquote>
  1938. <p>foo
  1939. bar</p>
  1940. </blockquote>
  1941. </blockquote>
  1942. </blockquote>
  1943. .
  1944. .
  1945. >>> foo
  1946. > bar
  1947. >>baz
  1948. .
  1949. <blockquote>
  1950. <blockquote>
  1951. <blockquote>
  1952. <p>foo
  1953. bar
  1954. baz</p>
  1955. </blockquote>
  1956. </blockquote>
  1957. </blockquote>
  1958. .
  1959. When including an indented code block in a block quote,
  1960. remember that the [block quote marker](#block-quote-marker) includes
  1961. both the `>` and a following space. So *five spaces* are needed after
  1962. the `>`:
  1963. .
  1964. > code
  1965. > not code
  1966. .
  1967. <blockquote>
  1968. <pre><code>code
  1969. </code></pre>
  1970. </blockquote>
  1971. <blockquote>
  1972. <p>not code</p>
  1973. </blockquote>
  1974. .
  1975. ## List items
  1976. A [list marker](#list-marker) <a id="list-marker"></a> is a
  1977. [bullet list marker](#bullet-list-marker) or an [ordered list
  1978. marker](#ordered-list-marker).
  1979. A [bullet list marker](#bullet-list-marker) <a id="bullet-list-marker"></a>
  1980. is a `-`, `+`, or `*` character.
  1981. An [ordered list marker](#ordered-list-marker) <a id="ordered-list-marker"></a>
  1982. is a sequence of one of more digits (`0-9`), followed by either a
  1983. `.` character or a `)` character.
  1984. The following rules define [list items](#list-item):<a
  1985. id="list-item"></a>
  1986. 1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of
  1987. blocks *Bs* starting with a non-space character and not separated
  1988. from each other by more than one blank line, and *M* is a list
  1989. marker *M* of width *W* followed by 0 < *N* < 5 spaces, then the result
  1990. of prepending *M* and the following spaces to the first line of
  1991. *Ls*, and indenting subsequent lines of *Ls* by *W + N* spaces, is a
  1992. list item with *Bs* as its contents. The type of the list item
  1993. (bullet or ordered) is determined by the type of its list marker.
  1994. If the list item is ordered, then it is also assigned a start
  1995. number, based on the ordered list marker.
  1996. For example, let *Ls* be the lines
  1997. .
  1998. A paragraph
  1999. with two lines.
  2000. indented code
  2001. > A block quote.
  2002. .
  2003. <p>A paragraph
  2004. with two lines.</p>
  2005. <pre><code>indented code
  2006. </code></pre>
  2007. <blockquote>
  2008. <p>A block quote.</p>
  2009. </blockquote>
  2010. .
  2011. And let *M* be the marker `1.`, and *N* = 2. Then rule #1 says
  2012. that the following is an ordered list item with start number 1,
  2013. and the same contents as *Ls*:
  2014. .
  2015. 1. A paragraph
  2016. with two lines.
  2017. indented code
  2018. > A block quote.
  2019. .
  2020. <ol>
  2021. <li><p>A paragraph
  2022. with two lines.</p>
  2023. <pre><code>indented code
  2024. </code></pre>
  2025. <blockquote>
  2026. <p>A block quote.</p>
  2027. </blockquote></li>
  2028. </ol>
  2029. .
  2030. The most important thing to notice is that the position of
  2031. the text after the list marker determines how much indentation
  2032. is needed in subsequent blocks in the list item. If the list
  2033. marker takes up two spaces, and there are three spaces between
  2034. the list marker and the next nonspace character, then blocks
  2035. must be indented five spaces in order to fall under the list
  2036. item.
  2037. Here are some examples showing how far content must be indented to be
  2038. put under the list item:
  2039. .
  2040. - one
  2041. two
  2042. .
  2043. <ul>
  2044. <li>one</li>
  2045. </ul>
  2046. <p>two</p>
  2047. .
  2048. .
  2049. - one
  2050. two
  2051. .
  2052. <ul>
  2053. <li><p>one</p>
  2054. <p>two</p></li>
  2055. </ul>
  2056. .
  2057. .
  2058. - one
  2059. two
  2060. .
  2061. <ul>
  2062. <li>one</li>
  2063. </ul>
  2064. <pre><code> two
  2065. </code></pre>
  2066. .
  2067. .
  2068. - one
  2069. two
  2070. .
  2071. <ul>
  2072. <li><p>one</p>
  2073. <p>two</p></li>
  2074. </ul>
  2075. .
  2076. It is tempting to think of this in terms of columns: the continuation
  2077. blocks must be indented at least to the column of the first nonspace
  2078. character after the list marker. However, that is not quite right.
  2079. The spaces after the list marker determine how much relative indentation
  2080. is needed. Which column this indentation reaches will depend on
  2081. how the list item is embedded in other constructions, as shown by
  2082. this example:
  2083. .
  2084. > > 1. one
  2085. >>
  2086. >> two
  2087. .
  2088. <blockquote>
  2089. <blockquote>
  2090. <ol>
  2091. <li><p>one</p>
  2092. <p>two</p></li>
  2093. </ol>
  2094. </blockquote>
  2095. </blockquote>
  2096. .
  2097. Here `two` occurs in the same column as the list marker `1.`,
  2098. but is actually contained in the list item, because there is
  2099. sufficent indentation after the last containing blockquote marker.
  2100. The converse is also possible. In the following example, the word `two`
  2101. occurs far to the right of the initial text of the list item, `one`, but
  2102. it is not considered part of the list item, because it is not indented
  2103. far enough past the blockquote marker:
  2104. .
  2105. >>- one
  2106. >>
  2107. > > two
  2108. .
  2109. <blockquote>
  2110. <blockquote>
  2111. <ul>
  2112. <li>one</li>
  2113. </ul>
  2114. <p>two</p>
  2115. </blockquote>
  2116. </blockquote>
  2117. .
  2118. A list item may not contain blocks that are separated by more than
  2119. one blank line. Thus, two blank lines will end a list, unless the
  2120. two blanks are contained in a [fenced code block](#fenced-code-block).
  2121. .
  2122. - foo
  2123. bar
  2124. - foo
  2125. bar
  2126. - ```
  2127. foo
  2128. bar
  2129. ```
  2130. .
  2131. <ul>
  2132. <li><p>foo</p>
  2133. <p>bar</p></li>
  2134. <li><p>foo</p></li>
  2135. </ul>
  2136. <p>bar</p>
  2137. <ul>
  2138. <li><pre><code>foo
  2139. bar
  2140. </code></pre></li>
  2141. </ul>
  2142. .
  2143. A list item may contain any kind of block:
  2144. .
  2145. 1. foo
  2146. ```
  2147. bar
  2148. ```
  2149. baz
  2150. > bam
  2151. .
  2152. <ol>
  2153. <li><p>foo</p>
  2154. <pre><code>bar
  2155. </code></pre>
  2156. <p>baz</p>
  2157. <blockquote>
  2158. <p>bam</p>
  2159. </blockquote></li>
  2160. </ol>
  2161. .
  2162. 2. **Item starting with indented code.** If a sequence of lines *Ls*
  2163. constitute a sequence of blocks *Bs* starting with an indented code
  2164. block and not separated from each other by more than one blank line,
  2165. and *M* is a list marker *M* of width *W* followed by
  2166. one space, then the result of prepending *M* and the following
  2167. space to the first line of *Ls*, and indenting subsequent lines of
  2168. *Ls* by *W + 1* spaces, is a list item with *Bs* as its contents.
  2169. If a line is empty, then it need not be indented. The type of the
  2170. list item (bullet or ordered) is determined by the type of its list
  2171. marker. If the list item is ordered, then it is also assigned a
  2172. start number, based on the ordered list marker.
  2173. An indented code block will have to be indented four spaces beyond
  2174. the edge of the region where text will be included in the list item.
  2175. In the following case that is 6 spaces:
  2176. .
  2177. - foo
  2178. bar
  2179. .
  2180. <ul>
  2181. <li><p>foo</p>
  2182. <pre><code>bar
  2183. </code></pre></li>
  2184. </ul>
  2185. .
  2186. And in this case it is 11 spaces:
  2187. .
  2188. 10. foo
  2189. bar
  2190. .
  2191. <ol start="10">
  2192. <li><p>foo</p>
  2193. <pre><code>bar
  2194. </code></pre></li>
  2195. </ol>
  2196. .
  2197. If the *first* block in the list item is an indented code block,
  2198. then by rule #2, the contents must be indented *one* space after the
  2199. list marker:
  2200. .
  2201. indented code
  2202. paragraph
  2203. more code
  2204. .
  2205. <pre><code>indented code
  2206. </code></pre>
  2207. <p>paragraph</p>
  2208. <pre><code>more code
  2209. </code></pre>
  2210. .
  2211. .
  2212. 1. indented code
  2213. paragraph
  2214. more code
  2215. .
  2216. <ol>
  2217. <li><pre><code>indented code
  2218. </code></pre>
  2219. <p>paragraph</p>
  2220. <pre><code>more code
  2221. </code></pre></li>
  2222. </ol>
  2223. .
  2224. Note that an additional space indent is interpreted as space
  2225. inside the code block:
  2226. .
  2227. 1. indented code
  2228. paragraph
  2229. more code
  2230. .
  2231. <ol>
  2232. <li><pre><code> indented code
  2233. </code></pre>
  2234. <p>paragraph</p>
  2235. <pre><code>more code
  2236. </code></pre></li>
  2237. </ol>
  2238. .
  2239. Note that rules #1 and #2 only apply to two cases: (a) cases
  2240. in which the lines to be included in a list item begin with a nonspace
  2241. character, and (b) cases in which they begin with an indented code
  2242. block. In a case like the following, where the first block begins with
  2243. a three-space indent, the rules do not allow us to form a list item by
  2244. indenting the whole thing and prepending a list marker:
  2245. .
  2246. foo
  2247. bar
  2248. .
  2249. <p>foo</p>
  2250. <p>bar</p>
  2251. .
  2252. .
  2253. - foo
  2254. bar
  2255. .
  2256. <ul>
  2257. <li>foo</li>
  2258. </ul>
  2259. <p>bar</p>
  2260. .
  2261. This is not a significant restriction, because when a block begins
  2262. with 1-3 spaces indent, the indentation can always be removed without
  2263. a change in interpretation, allowing rule #1 to be applied. So, in
  2264. the above case:
  2265. .
  2266. - foo
  2267. bar
  2268. .
  2269. <ul>
  2270. <li><p>foo</p>
  2271. <p>bar</p></li>
  2272. </ul>
  2273. .
  2274. 3. **Indentation.** If a sequence of lines *Ls* constitutes a list item
  2275. according to rule #1 or #2, then the result of indenting each line
  2276. of *L* by 1-3 spaces (the same for each line) also constitutes a
  2277. list item with the same contents and attributes. If a line is
  2278. empty, then it need not be indented.
  2279. Indented one space:
  2280. .
  2281. 1. A paragraph
  2282. with two lines.
  2283. indented code
  2284. > A block quote.
  2285. .
  2286. <ol>
  2287. <li><p>A paragraph
  2288. with two lines.</p>
  2289. <pre><code>indented code
  2290. </code></pre>
  2291. <blockquote>
  2292. <p>A block quote.</p>
  2293. </blockquote></li>
  2294. </ol>
  2295. .
  2296. Indented two spaces:
  2297. .
  2298. 1. A paragraph
  2299. with two lines.
  2300. indented code
  2301. > A block quote.
  2302. .
  2303. <ol>
  2304. <li><p>A paragraph
  2305. with two lines.</p>
  2306. <pre><code>indented code
  2307. </code></pre>
  2308. <blockquote>
  2309. <p>A block quote.</p>
  2310. </blockquote></li>
  2311. </ol>
  2312. .
  2313. Indented three spaces:
  2314. .
  2315. 1. A paragraph
  2316. with two lines.
  2317. indented code
  2318. > A block quote.
  2319. .
  2320. <ol>
  2321. <li><p>A paragraph
  2322. with two lines.</p>
  2323. <pre><code>indented code
  2324. </code></pre>
  2325. <blockquote>
  2326. <p>A block quote.</p>
  2327. </blockquote></li>
  2328. </ol>
  2329. .
  2330. Four spaces indent gives a code block:
  2331. .
  2332. 1. A paragraph
  2333. with two lines.
  2334. indented code
  2335. > A block quote.
  2336. .
  2337. <pre><code>1. A paragraph
  2338. with two lines.
  2339. indented code
  2340. &gt; A block quote.
  2341. </code></pre>
  2342. .
  2343. 4. **Laziness.** If a string of lines *Ls* constitute a [list
  2344. item](#list-item) with contents *Bs*, then the result of deleting
  2345. some or all of the indentation from one or more lines in which the
  2346. next non-space character after the indentation is
  2347. [paragraph continuation text](#paragraph-continuation-text) is a
  2348. list item with the same contents and attributes.<a
  2349. id="lazy-continuation-line"></a>
  2350. Here is an example with [lazy continuation
  2351. lines](#lazy-continuation-line):
  2352. .
  2353. 1. A paragraph
  2354. with two lines.
  2355. indented code
  2356. > A block quote.
  2357. .
  2358. <ol>
  2359. <li><p>A paragraph
  2360. with two lines.</p>
  2361. <pre><code>indented code
  2362. </code></pre>
  2363. <blockquote>
  2364. <p>A block quote.</p>
  2365. </blockquote></li>
  2366. </ol>
  2367. .
  2368. Indentation can be partially deleted:
  2369. .
  2370. 1. A paragraph
  2371. with two lines.
  2372. .
  2373. <ol>
  2374. <li>A paragraph
  2375. with two lines.</li>
  2376. </ol>
  2377. .
  2378. These examples show how laziness can work in nested structures:
  2379. .
  2380. > 1. > Blockquote
  2381. continued here.
  2382. .
  2383. <blockquote>
  2384. <ol>
  2385. <li><blockquote>
  2386. <p>Blockquote
  2387. continued here.</p>
  2388. </blockquote></li>
  2389. </ol>
  2390. </blockquote>
  2391. .
  2392. .
  2393. > 1. > Blockquote
  2394. > continued here.
  2395. .
  2396. <blockquote>
  2397. <ol>
  2398. <li><blockquote>
  2399. <p>Blockquote
  2400. continued here.</p>
  2401. </blockquote></li>
  2402. </ol>
  2403. </blockquote>
  2404. .
  2405. 5. **That's all.** Nothing that is not counted as a list item by rules
  2406. #1--4 counts as a [list item](#list-item).
  2407. The rules for sublists follow from the general rules above. A sublist
  2408. must be indented the same number of spaces a paragraph would need to be
  2409. in order to be included in the list item.
  2410. So, in this case we need two spaces indent:
  2411. .
  2412. - foo
  2413. - bar
  2414. - baz
  2415. .
  2416. <ul>
  2417. <li>foo
  2418. <ul>
  2419. <li>bar
  2420. <ul>
  2421. <li>baz</li>
  2422. </ul></li>
  2423. </ul></li>
  2424. </ul>
  2425. .
  2426. One is not enough:
  2427. .
  2428. - foo
  2429. - bar
  2430. - baz
  2431. .
  2432. <ul>
  2433. <li>foo</li>
  2434. <li>bar</li>
  2435. <li>baz</li>
  2436. </ul>
  2437. .
  2438. Here we need four, because the list marker is wider:
  2439. .
  2440. 10) foo
  2441. - bar
  2442. .
  2443. <ol start="10">
  2444. <li>foo
  2445. <ul>
  2446. <li>bar</li>
  2447. </ul></li>
  2448. </ol>
  2449. .
  2450. Three is not enough:
  2451. .
  2452. 10) foo
  2453. - bar
  2454. .
  2455. <ol start="10">
  2456. <li>foo</li>
  2457. </ol>
  2458. <ul>
  2459. <li>bar</li>
  2460. </ul>
  2461. .
  2462. A list may be the first block in a list item:
  2463. .
  2464. - - foo
  2465. .
  2466. <ul>
  2467. <li><ul>
  2468. <li>foo</li>
  2469. </ul></li>
  2470. </ul>
  2471. .
  2472. .
  2473. 1. - 2. foo
  2474. .
  2475. <ol>
  2476. <li><ul>
  2477. <li><ol start="2">
  2478. <li>foo</li>
  2479. </ol></li>
  2480. </ul></li>
  2481. </ol>
  2482. .
  2483. A list item may be empty:
  2484. .
  2485. - foo
  2486. -
  2487. - bar
  2488. .
  2489. <ul>
  2490. <li>foo</li>
  2491. <li></li>
  2492. <li>bar</li>
  2493. </ul>
  2494. .
  2495. .
  2496. -
  2497. .
  2498. <ul>
  2499. <li></li>
  2500. </ul>
  2501. .
  2502. A list item can contain a header:
  2503. .
  2504. - # Foo
  2505. - Bar
  2506. ---
  2507. baz
  2508. .
  2509. <ul>
  2510. <li><h1>Foo</h1></li>
  2511. <li><h2>Bar</h2>
  2512. <p>baz</p></li>
  2513. </ul>
  2514. .
  2515. ### Motivation
  2516. John Gruber's Markdown spec says the following about list items:
  2517. 1. "List markers typically start at the left margin, but may be indented
  2518. by up to three spaces. List markers must be followed by one or more
  2519. spaces or a tab."
  2520. 2. "To make lists look nice, you can wrap items with hanging indents....
  2521. But if you don't want to, you don't have to."
  2522. 3. "List items may consist of multiple paragraphs. Each subsequent
  2523. paragraph in a list item must be indented by either 4 spaces or one
  2524. tab."
  2525. 4. "It looks nice if you indent every line of the subsequent paragraphs,
  2526. but here again, Markdown will allow you to be lazy."
  2527. 5. "To put a blockquote within a list item, the blockquote's `>`
  2528. delimiters need to be indented."
  2529. 6. "To put a code block within a list item, the code block needs to be
  2530. indented twice — 8 spaces or two tabs."
  2531. These rules specify that a paragraph under a list item must be indented
  2532. four spaces (presumably, from the left margin, rather than the start of
  2533. the list marker, but this is not said), and that code under a list item
  2534. must be indented eight spaces instead of the usual four. They also say
  2535. that a block quote must be indented, but not by how much; however, the
  2536. example given has four spaces indentation. Although nothing is said
  2537. about other kinds of block-level content, it is certainly reasonable to
  2538. infer that *all* block elements under a list item, including other
  2539. lists, must be indented four spaces. This principle has been called the
  2540. *four-space rule*.
  2541. The four-space rule is clear and principled, and if the reference
  2542. implementation `Markdown.pl` had followed it, it probably would have
  2543. become the standard. However, `Markdown.pl` allowed paragraphs and
  2544. sublists to start with only two spaces indentation, at least on the
  2545. outer level. Worse, its behavior was inconsistent: a sublist of an
  2546. outer-level list needed two spaces indentation, but a sublist of this
  2547. sublist needed three spaces. It is not surprising, then, that different
  2548. implementations of Markdown have developed very different rules for
  2549. determining what comes under a list item. (Pandoc and python-Markdown,
  2550. for example, stuck with Gruber's syntax description and the four-space
  2551. rule, while discount, redcarpet, marked, PHP Markdown, and others
  2552. followed `Markdown.pl`'s behavior more closely.)
  2553. Unfortunately, given the divergences between implementations, there
  2554. is no way to give a spec for list items that will be guaranteed not
  2555. to break any existing documents. However, the spec given here should
  2556. correctly handle lists formatted with either the four-space rule or
  2557. the more forgiving `Markdown.pl` behavior, provided they are laid out
  2558. in a way that is natural for a human to read.
  2559. The strategy here is to let the width and indentation of the list marker
  2560. determine the indentation necessary for blocks to fall under the list
  2561. item, rather than having a fixed and arbitrary number. The writer can
  2562. think of the body of the list item as a unit which gets indented to the
  2563. right enough to fit the list marker (and any indentation on the list
  2564. marker). (The laziness rule, #4, then allows continuation lines to be
  2565. unindented if needed.)
  2566. This rule is superior, we claim, to any rule requiring a fixed level of
  2567. indentation from the margin. The four-space rule is clear but
  2568. unnatural. It is quite unintuitive that
  2569. ``` markdown
  2570. - foo
  2571. bar
  2572. - baz
  2573. ```
  2574. should be parsed as two lists with an intervening paragraph,
  2575. ``` html
  2576. <ul>
  2577. <li>foo</li>
  2578. </ul>
  2579. <p>bar</p>
  2580. <ul>
  2581. <li>baz</li>
  2582. </ul>
  2583. ```
  2584. as the four-space rule demands, rather than a single list,
  2585. ``` html
  2586. <ul>
  2587. <li><p>foo</p>
  2588. <p>bar</p>
  2589. <ul>
  2590. <li>baz</li>
  2591. </ul></li>
  2592. </ul>
  2593. ```
  2594. The choice of four spaces is arbitrary. It can be learned, but it is
  2595. not likely to be guessed, and it trips up beginners regularly.
  2596. Would it help to adopt a two-space rule? The problem is that such
  2597. a rule, together with the rule allowing 1--3 spaces indentation of the
  2598. initial list marker, allows text that is indented *less than* the
  2599. original list marker to be included in the list item. For example,
  2600. `Markdown.pl` parses
  2601. ``` markdown
  2602. - one
  2603. two
  2604. ```
  2605. as a single list item, with `two` a continuation paragraph:
  2606. ``` html
  2607. <ul>
  2608. <li><p>one</p>
  2609. <p>two</p></li>
  2610. </ul>
  2611. ```
  2612. and similarly
  2613. ``` markdown
  2614. > - one
  2615. >
  2616. > two
  2617. ```
  2618. as
  2619. ``` html
  2620. <blockquote>
  2621. <ul>
  2622. <li><p>one</p>
  2623. <p>two</p></li>
  2624. </ul>
  2625. </blockquote>
  2626. ```
  2627. This is extremely unintuitive.
  2628. Rather than requiring a fixed indent from the margin, we could require
  2629. a fixed indent (say, two spaces, or even one space) from the list marker (which
  2630. may itself be indented). This proposal would remove the last anomaly
  2631. discussed. Unlike the spec presented above, it would count the following
  2632. as a list item with a subparagraph, even though the paragraph `bar`
  2633. is not indented as far as the first paragraph `foo`:
  2634. ``` markdown
  2635. 10. foo
  2636. bar
  2637. ```
  2638. Arguably this text does read like a list item with `bar` as a subparagraph,
  2639. which may count in favor of the proposal. However, on this proposal indented
  2640. code would have to be indented six spaces after the list marker. And this
  2641. would break a lot of existing Markdown, which has the pattern:
  2642. ``` markdown
  2643. 1. foo
  2644. indented code
  2645. ```
  2646. where the code is indented eight spaces. The spec above, by contrast, will
  2647. parse this text as expected, since the code block's indentation is measured
  2648. from the beginning of `foo`.
  2649. The one case that needs special treatment is a list item that *starts*
  2650. with indented code. How much indentation is required in that case, since
  2651. we don't have a "first paragraph" to measure from? Rule #2 simply stipulates
  2652. that in such cases, we require one space indentation from the list marker
  2653. (and then the normal four spaces for the indented code). This will match the
  2654. four-space rule in cases where the list marker plus its initial indentation
  2655. takes four spaces (a common case), but diverge in other cases.
  2656. ## Lists
  2657. A [list](#list) <a id="list"></a> is a sequence of one or more
  2658. list items [of the same type](#of-the-same-type). The list items
  2659. may be separated by single [blank lines](#blank-line), but two
  2660. blank lines end all containing lists.
  2661. Two list items are [of the same type](#of-the-same-type)
  2662. <a id="of-the-same-type"></a> if they begin with a [list
  2663. marker](#list-marker) of the same type. Two list markers are of the
  2664. same type if (a) they are bullet list markers using the same character
  2665. (`-`, `+`, or `*`) or (b) they are ordered list numbers with the same
  2666. delimiter (either `.` or `)`).
  2667. A list is an [ordered list](#ordered-list) <a id="ordered-list"></a>
  2668. if its constituent list items begin with
  2669. [ordered list markers](#ordered-list-marker), and a [bullet
  2670. list](#bullet-list) <a id="bullet-list"></a> if its constituent list
  2671. items begin with [bullet list markers](#bullet-list-marker).
  2672. The [start number](#start-number) <a id="start-number"></a>
  2673. of an [ordered list](#ordered-list) is determined by the list number of
  2674. its initial list item. The numbers of subsequent list items are
  2675. disregarded.
  2676. A list is [loose](#loose)<a id="loose"></a> if it any of its constituent
  2677. list items are separated by blank lines, or if any of its constituent
  2678. list items directly contain two block-level elements with a blank line
  2679. between them. Otherwise a list is [tight](#tight).<a id="tight"></a>
  2680. (The difference in HTML output is that paragraphs in a loose list are
  2681. wrapped in `<p>` tags, while paragraphs in a tight list are not.)
  2682. Changing the bullet or ordered list delimiter starts a new list:
  2683. .
  2684. - foo
  2685. - bar
  2686. + baz
  2687. .
  2688. <ul>
  2689. <li>foo</li>
  2690. <li>bar</li>
  2691. </ul>
  2692. <ul>
  2693. <li>baz</li>
  2694. </ul>
  2695. .
  2696. .
  2697. 1. foo
  2698. 2. bar
  2699. 3) baz
  2700. .
  2701. <ol>
  2702. <li>foo</li>
  2703. <li>bar</li>
  2704. </ol>
  2705. <ol start="3">
  2706. <li>baz</li>
  2707. </ol>
  2708. .
  2709. In CommonMark, a list can interrupt a paragraph. That is,
  2710. no blank line is needed to separate a paragraph from a following
  2711. list:
  2712. .
  2713. Foo
  2714. - bar
  2715. - baz
  2716. .
  2717. <p>Foo</p>
  2718. <ul>
  2719. <li>bar</li>
  2720. <li>baz</li>
  2721. </ul>
  2722. .
  2723. `Markdown.pl` does not allow this, through fear of triggering a list
  2724. via a numeral in a hard-wrapped line:
  2725. .
  2726. The number of windows in my house is
  2727. 14. The number of doors is 6.
  2728. .
  2729. <p>The number of windows in my house is</p>
  2730. <ol start="14">
  2731. <li>The number of doors is 6.</li>
  2732. </ol>
  2733. .
  2734. Oddly, `Markdown.pl` *does* allow a blockquote to interrupt a paragraph,
  2735. even though the same considerations might apply. We think that the two
  2736. cases should be treated the same. Here are two reasons for allowing
  2737. lists to interrupt paragraphs:
  2738. First, it is natural and not uncommon for people to start lists without
  2739. blank lines:
  2740. I need to buy
  2741. - new shoes
  2742. - a coat
  2743. - a plane ticket
  2744. Second, we are attracted to a
  2745. > [principle of uniformity](#principle-of-uniformity):<a
  2746. > id="principle-of-uniformity"></a> if a span of text has a certain
  2747. > meaning, it will continue to have the same meaning when put into a list
  2748. > item.
  2749. (Indeed, the spec for [list items](#list-item) presupposes this.)
  2750. This principle implies that if
  2751. * I need to buy
  2752. - new shoes
  2753. - a coat
  2754. - a plane ticket
  2755. is a list item containing a paragraph followed by a nested sublist,
  2756. as all Markdown implementations agree it is (though the paragraph
  2757. may be rendered without `<p>` tags, since the list is "tight"),
  2758. then
  2759. I need to buy
  2760. - new shoes
  2761. - a coat
  2762. - a plane ticket
  2763. by itself should be a paragraph followed by a nested sublist.
  2764. Our adherence to the [principle of uniformity](#principle-of-uniformity)
  2765. thus inclines us to think that there are two coherent packages:
  2766. 1. Require blank lines before *all* lists and blockquotes,
  2767. including lists that occur as sublists inside other list items.
  2768. 2. Require blank lines in none of these places.
  2769. [reStructuredText](http://docutils.sourceforge.net/rst.html) takes
  2770. the first approach, for which there is much to be said. But the second
  2771. seems more consistent with established practice with Markdown.
  2772. There can be blank lines between items, but two blank lines end
  2773. a list:
  2774. .
  2775. - foo
  2776. - bar
  2777. - baz
  2778. .
  2779. <ul>
  2780. <li><p>foo</p></li>
  2781. <li><p>bar</p></li>
  2782. </ul>
  2783. <ul>
  2784. <li>baz</li>
  2785. </ul>
  2786. .
  2787. As illustrated above in the section on [list items](#list-item),
  2788. two blank lines between blocks *within* a list item will also end a
  2789. list:
  2790. .
  2791. - foo
  2792. bar
  2793. - baz
  2794. .
  2795. <ul>
  2796. <li>foo</li>
  2797. </ul>
  2798. <p>bar</p>
  2799. <ul>
  2800. <li>baz</li>
  2801. </ul>
  2802. .
  2803. Indeed, two blank lines will end *all* containing lists:
  2804. .
  2805. - foo
  2806. - bar
  2807. - baz
  2808. bim
  2809. .
  2810. <ul>
  2811. <li>foo
  2812. <ul>
  2813. <li>bar
  2814. <ul>
  2815. <li>baz</li>
  2816. </ul></li>
  2817. </ul></li>
  2818. </ul>
  2819. <pre><code> bim
  2820. </code></pre>
  2821. .
  2822. Thus, two blank lines can be used to separate consecutive lists of
  2823. the same type, or to separate a list from an indented code block
  2824. that would otherwise be parsed as a subparagraph of the final list
  2825. item:
  2826. .
  2827. - foo
  2828. - bar
  2829. - baz
  2830. - bim
  2831. .
  2832. <ul>
  2833. <li>foo</li>
  2834. <li>bar</li>
  2835. </ul>
  2836. <ul>
  2837. <li>baz</li>
  2838. <li>bim</li>
  2839. </ul>
  2840. .
  2841. .
  2842. - foo
  2843. notcode
  2844. - foo
  2845. code
  2846. .
  2847. <ul>
  2848. <li><p>foo</p>
  2849. <p>notcode</p></li>
  2850. <li><p>foo</p></li>
  2851. </ul>
  2852. <pre><code>code
  2853. </code></pre>
  2854. .
  2855. List items need not be indented to the same level. The following
  2856. list items will be treated as items at the same list level,
  2857. since none is indented enough to belong to the previous list
  2858. item:
  2859. .
  2860. - a
  2861. - b
  2862. - c
  2863. - d
  2864. - e
  2865. - f
  2866. - g
  2867. .
  2868. <ul>
  2869. <li>a</li>
  2870. <li>b</li>
  2871. <li>c</li>
  2872. <li>d</li>
  2873. <li>e</li>
  2874. <li>f</li>
  2875. <li>g</li>
  2876. </ul>
  2877. .
  2878. This is a loose list, because there is a blank line between
  2879. two of the list items:
  2880. .
  2881. - a
  2882. - b
  2883. - c
  2884. .
  2885. <ul>
  2886. <li><p>a</p></li>
  2887. <li><p>b</p></li>
  2888. <li><p>c</p></li>
  2889. </ul>
  2890. .
  2891. So is this, with a empty second item:
  2892. .
  2893. * a
  2894. *
  2895. * c
  2896. .
  2897. <ul>
  2898. <li><p>a</p></li>
  2899. <li></li>
  2900. <li><p>c</p></li>
  2901. </ul>
  2902. .
  2903. These are loose lists, even though there is no space between the items,
  2904. because one of the items directly contains two block-level elements
  2905. with a blank line between them:
  2906. .
  2907. - a
  2908. - b
  2909. c
  2910. - d
  2911. .
  2912. <ul>
  2913. <li><p>a</p></li>
  2914. <li><p>b</p>
  2915. <p>c</p></li>
  2916. <li><p>d</p></li>
  2917. </ul>
  2918. .
  2919. .
  2920. - a
  2921. - b
  2922. [ref]: /url
  2923. - d
  2924. .
  2925. <ul>
  2926. <li><p>a</p></li>
  2927. <li><p>b</p></li>
  2928. <li><p>d</p></li>
  2929. </ul>
  2930. .
  2931. This is a tight list, because the blank lines are in a code block:
  2932. .
  2933. - a
  2934. - ```
  2935. b
  2936. ```
  2937. - c
  2938. .
  2939. <ul>
  2940. <li>a</li>
  2941. <li><pre><code>b
  2942. </code></pre></li>
  2943. <li>c</li>
  2944. </ul>
  2945. .
  2946. This is a tight list, because the blank line is between two
  2947. paragraphs of a sublist. So the sublist is loose while
  2948. the outer list is tight:
  2949. .
  2950. - a
  2951. - b
  2952. c
  2953. - d
  2954. .
  2955. <ul>
  2956. <li>a
  2957. <ul>
  2958. <li><p>b</p>
  2959. <p>c</p></li>
  2960. </ul></li>
  2961. <li>d</li>
  2962. </ul>
  2963. .
  2964. This is a tight list, because the blank line is inside the
  2965. block quote:
  2966. .
  2967. * a
  2968. > b
  2969. >
  2970. * c
  2971. .
  2972. <ul>
  2973. <li>a
  2974. <blockquote>
  2975. <p>b</p>
  2976. </blockquote></li>
  2977. <li>c</li>
  2978. </ul>
  2979. .
  2980. This list is tight, because the consecutive block elements
  2981. are not separated by blank lines:
  2982. .
  2983. - a
  2984. > b
  2985. ```
  2986. c
  2987. ```
  2988. - d
  2989. .
  2990. <ul>
  2991. <li>a
  2992. <blockquote>
  2993. <p>b</p>
  2994. </blockquote>
  2995. <pre><code>c
  2996. </code></pre></li>
  2997. <li>d</li>
  2998. </ul>
  2999. .
  3000. A single-paragraph list is tight:
  3001. .
  3002. - a
  3003. .
  3004. <ul>
  3005. <li>a</li>
  3006. </ul>
  3007. .
  3008. .
  3009. - a
  3010. - b
  3011. .
  3012. <ul>
  3013. <li>a
  3014. <ul>
  3015. <li>b</li>
  3016. </ul></li>
  3017. </ul>
  3018. .
  3019. Here the outer list is loose, the inner list tight:
  3020. .
  3021. * foo
  3022. * bar
  3023. baz
  3024. .
  3025. <ul>
  3026. <li><p>foo</p>
  3027. <ul>
  3028. <li>bar</li>
  3029. </ul>
  3030. <p>baz</p></li>
  3031. </ul>
  3032. .
  3033. .
  3034. - a
  3035. - b
  3036. - c
  3037. - d
  3038. - e
  3039. - f
  3040. .
  3041. <ul>
  3042. <li><p>a</p>
  3043. <ul>
  3044. <li>b</li>
  3045. <li>c</li>
  3046. </ul></li>
  3047. <li><p>d</p>
  3048. <ul>
  3049. <li>e</li>
  3050. <li>f</li>
  3051. </ul></li>
  3052. </ul>
  3053. .
  3054. # Inlines
  3055. Inlines are parsed sequentially from the beginning of the character
  3056. stream to the end (left to right, in left-to-right languages).
  3057. Thus, for example, in
  3058. .
  3059. `hi`lo`
  3060. .
  3061. <p><code>hi</code>lo`</p>
  3062. .
  3063. `hi` is parsed as code, leaving the backtick at the end as a literal
  3064. backtick.
  3065. ## Backslash escapes
  3066. Any ASCII punctuation character may be backslash-escaped:
  3067. .
  3068. \!\"\#\$\%\&\'\(\)\*\+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}\~
  3069. .
  3070. <p>!&quot;#$%&amp;'()*+,-./:;&lt;=&gt;?@[\]^_`{|}~</p>
  3071. .
  3072. Backslashes before other characters are treated as literal
  3073. backslashes:
  3074. .
  3075. \→\A\a\ \3\φ\«
  3076. .
  3077. <p>\ \A\a\ \3\φ\«</p>
  3078. .
  3079. Escaped characters are treated as regular characters and do
  3080. not have their usual Markdown meanings:
  3081. .
  3082. \*not emphasized*
  3083. \<br/> not a tag
  3084. \[not a link](/foo)
  3085. \`not code`
  3086. 1\. not a list
  3087. \* not a list
  3088. \# not a header
  3089. \[foo]: /url "not a reference"
  3090. .
  3091. <p>*not emphasized*
  3092. &lt;br/&gt; not a tag
  3093. [not a link](/foo)
  3094. `not code`
  3095. 1. not a list
  3096. * not a list
  3097. # not a header
  3098. [foo]: /url &quot;not a reference&quot;</p>
  3099. .
  3100. If a backslash is itself escaped, the following character is not:
  3101. .
  3102. \\*emphasis*
  3103. .
  3104. <p>\<em>emphasis</em></p>
  3105. .
  3106. A backslash at the end of the line is a [hard line
  3107. break](#hard-line-break):
  3108. .
  3109. foo\
  3110. bar
  3111. .
  3112. <p>foo<br />
  3113. bar</p>
  3114. .
  3115. Backslash escapes do not work in code blocks, code spans, autolinks, or
  3116. raw HTML:
  3117. .
  3118. `` \[\` ``
  3119. .
  3120. <p><code>\[\`</code></p>
  3121. .
  3122. .
  3123. \[\]
  3124. .
  3125. <pre><code>\[\]
  3126. </code></pre>
  3127. .
  3128. .
  3129. ~~~
  3130. \[\]
  3131. ~~~
  3132. .
  3133. <pre><code>\[\]
  3134. </code></pre>
  3135. .
  3136. .
  3137. <http://example.com?find=\*>
  3138. .
  3139. <p><a href="http://example.com?find=%5C*">http://example.com?find=\*</a></p>
  3140. .
  3141. .
  3142. <a href="/bar\/)">
  3143. .
  3144. <p><a href="/bar\/)"></p>
  3145. .
  3146. But they work in all other contexts, including URLs and link titles,
  3147. link references, and info strings in [fenced code
  3148. blocks](#fenced-code-block):
  3149. .
  3150. [foo](/bar\* "ti\*tle")
  3151. .
  3152. <p><a href="/bar*" title="ti*tle">foo</a></p>
  3153. .
  3154. .
  3155. [foo]
  3156. [foo]: /bar\* "ti\*tle"
  3157. .
  3158. <p><a href="/bar*" title="ti*tle">foo</a></p>
  3159. .
  3160. .
  3161. ``` foo\+bar
  3162. foo
  3163. ```
  3164. .
  3165. <pre><code class="language-foo+bar">foo
  3166. </code></pre>
  3167. .
  3168. ## Entities
  3169. With the goal of making this standard as HTML-agnostic as possible, all
  3170. valid HTML entities in any context are recognized as such and
  3171. converted into unicode characters before they are stored in the AST.
  3172. This allows implementations that target HTML output to trivially escape
  3173. the entities when generating HTML, and simplifies the job of
  3174. implementations targetting other languages, as these will only need to
  3175. handle the unicode chars and need not be HTML-entity aware.
  3176. [Named entities](#name-entities) <a id="named-entities"></a> consist of `&`
  3177. + any of the valid HTML5 entity names + `;`. The
  3178. [following document](http://www.whatwg.org/specs/web-apps/current-work/multipage/entities.json)
  3179. is used as an authoritative source of the valid entity names and their
  3180. corresponding codepoints.
  3181. Conforming implementations that target HTML don't need to generate
  3182. entities for all the valid named entities that exist, with the exception
  3183. of `"` (`&quot;`), `&` (`&amp;`), `<` (`&lt;`) and `>` (`&gt;`), which
  3184. always need to be written as entities for security reasons.
  3185. .
  3186. &nbsp; &amp; &copy; &AElig; &Dcaron; &frac34; &HilbertSpace; &DifferentialD; &ClockwiseContourIntegral;
  3187. .
  3188. <p>  &amp; © Æ Ď ¾ ℋ ⅆ ∲</p>
  3189. .
  3190. [Decimal entities](#decimal-entities) <a id="decimal-entities"></a>
  3191. consist of `&#` + a string of 1--8 arabic digits + `;`. Again, these
  3192. entities need to be recognised and tranformed into their corresponding
  3193. UTF8 codepoints. Invalid Unicode codepoints will be written as the
  3194. "unknown codepoint" character (`0xFFFD`)
  3195. .
  3196. &#35; &#1234; &#992; &#98765432;
  3197. .
  3198. <p># Ӓ Ϡ �</p>
  3199. .
  3200. [Hexadecimal entities](#hexadecimal-entities) <a id="hexadecimal-entities"></a>
  3201. consist of `&#` + either `X` or `x` + a string of 1-8 hexadecimal digits
  3202. + `;`. They will also be parsed and turned into their corresponding UTF8 values in the AST.
  3203. .
  3204. &#X22; &#XD06; &#xcab;
  3205. .
  3206. <p>&quot; ആ ಫ</p>
  3207. .
  3208. Here are some nonentities:
  3209. .
  3210. &nbsp &x; &#; &#x; &ThisIsWayTooLongToBeAnEntityIsntIt; &hi?;
  3211. .
  3212. <p>&amp;nbsp &amp;x; &amp;#; &amp;#x; &amp;ThisIsWayTooLongToBeAnEntityIsntIt; &amp;hi?;</p>
  3213. .
  3214. Although HTML5 does accept some entities without a trailing semicolon
  3215. (such as `&copy`), these are not recognized as entities here, because it
  3216. makes the grammar too ambiguous:
  3217. .
  3218. &copy
  3219. .
  3220. <p>&amp;copy</p>
  3221. .
  3222. Strings that are not on the list of HTML5 named entities are not
  3223. recognized as entities either:
  3224. .
  3225. &MadeUpEntity;
  3226. .
  3227. <p>&amp;MadeUpEntity;</p>
  3228. .
  3229. Entities are recognized in any context besides code spans or
  3230. code blocks, including raw HTML, URLs, [link titles](#link-title), and
  3231. [fenced code block](#fenced-code-block) info strings:
  3232. .
  3233. <a href="&ouml;&ouml;.html">
  3234. .
  3235. <p><a href="&ouml;&ouml;.html"></p>
  3236. .
  3237. .
  3238. [foo](/f&ouml;&ouml; "f&ouml;&ouml;")
  3239. .
  3240. <p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
  3241. .
  3242. .
  3243. [foo]
  3244. [foo]: /f&ouml;&ouml; "f&ouml;&ouml;"
  3245. .
  3246. <p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
  3247. .
  3248. .
  3249. ``` f&ouml;&ouml;
  3250. foo
  3251. ```
  3252. .
  3253. <pre><code class="language-föö">foo
  3254. </code></pre>
  3255. .
  3256. Entities are treated as literal text in code spans and code blocks:
  3257. .
  3258. `f&ouml;&ouml;`
  3259. .
  3260. <p><code>f&amp;ouml;&amp;ouml;</code></p>
  3261. .
  3262. .
  3263. f&ouml;f&ouml;
  3264. .
  3265. <pre><code>f&amp;ouml;f&amp;ouml;
  3266. </code></pre>
  3267. .
  3268. ## Code span
  3269. A [backtick string](#backtick-string) <a id="backtick-string"></a>
  3270. is a string of one or more backtick characters (`` ` ``) that is neither
  3271. preceded nor followed by a backtick.
  3272. A code span begins with a backtick string and ends with a backtick
  3273. string of equal length. The contents of the code span are the
  3274. characters between the two backtick strings, with leading and trailing
  3275. spaces and newlines removed, and consecutive spaces and newlines
  3276. collapsed to single spaces.
  3277. This is a simple code span:
  3278. .
  3279. `foo`
  3280. .
  3281. <p><code>foo</code></p>
  3282. .
  3283. Here two backticks are used, because the code contains a backtick.
  3284. This example also illustrates stripping of leading and trailing spaces:
  3285. .
  3286. `` foo ` bar ``
  3287. .
  3288. <p><code>foo ` bar</code></p>
  3289. .
  3290. This example shows the motivation for stripping leading and trailing
  3291. spaces:
  3292. .
  3293. ` `` `
  3294. .
  3295. <p><code>``</code></p>
  3296. .
  3297. Newlines are treated like spaces:
  3298. .
  3299. ``
  3300. foo
  3301. ``
  3302. .
  3303. <p><code>foo</code></p>
  3304. .
  3305. Interior spaces and newlines are collapsed into single spaces, just
  3306. as they would be by a browser:
  3307. .
  3308. `foo bar
  3309. baz`
  3310. .
  3311. <p><code>foo bar baz</code></p>
  3312. .
  3313. Q: Why not just leave the spaces, since browsers will collapse them
  3314. anyway? A: Because we might be targeting a non-HTML format, and we
  3315. shouldn't rely on HTML-specific rendering assumptions.
  3316. (Existing implementations differ in their treatment of internal
  3317. spaces and newlines. Some, including `Markdown.pl` and
  3318. `showdown`, convert an internal newline into a `<br />` tag.
  3319. But this makes things difficult for those who like to hard-wrap
  3320. their paragraphs, since a line break in the midst of a code
  3321. span will cause an unintended line break in the output. Others
  3322. just leave internal spaces as they are, which is fine if only
  3323. HTML is being targeted.)
  3324. .
  3325. `foo `` bar`
  3326. .
  3327. <p><code>foo `` bar</code></p>
  3328. .
  3329. Note that backslash escapes do not work in code spans. All backslashes
  3330. are treated literally:
  3331. .
  3332. `foo\`bar`
  3333. .
  3334. <p><code>foo\</code>bar`</p>
  3335. .
  3336. Backslash escapes are never needed, because one can always choose a
  3337. string of *n* backtick characters as delimiters, where the code does
  3338. not contain any strings of exactly *n* backtick characters.
  3339. Code span backticks have higher precedence than any other inline
  3340. constructs except HTML tags and autolinks. Thus, for example, this is
  3341. not parsed as emphasized text, since the second `*` is part of a code
  3342. span:
  3343. .
  3344. *foo`*`
  3345. .
  3346. <p>*foo<code>*</code></p>
  3347. .
  3348. And this is not parsed as a link:
  3349. .
  3350. [not a `link](/foo`)
  3351. .
  3352. <p>[not a <code>link](/foo</code>)</p>
  3353. .
  3354. But this is a link:
  3355. .
  3356. <http://foo.bar.`baz>`
  3357. .
  3358. <p><a href="http://foo.bar.%60baz">http://foo.bar.`baz</a>`</p>
  3359. .
  3360. And this is an HTML tag:
  3361. .
  3362. <a href="`">`
  3363. .
  3364. <p><a href="`">`</p>
  3365. .
  3366. When a backtick string is not closed by a matching backtick string,
  3367. we just have literal backticks:
  3368. .
  3369. ```foo``
  3370. .
  3371. <p>```foo``</p>
  3372. .
  3373. .
  3374. `foo
  3375. .
  3376. <p>`foo</p>
  3377. .
  3378. ## Emphasis and strong emphasis
  3379. John Gruber's original [Markdown syntax
  3380. description](http://daringfireball.net/projects/markdown/syntax#em) says:
  3381. > Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
  3382. > emphasis. Text wrapped with one `*` or `_` will be wrapped with an HTML
  3383. > `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML `<strong>`
  3384. > tag.
  3385. This is enough for most users, but these rules leave much undecided,
  3386. especially when it comes to nested emphasis. The original
  3387. `Markdown.pl` test suite makes it clear that triple `***` and
  3388. `___` delimiters can be used for strong emphasis, and most
  3389. implementations have also allowed the following patterns:
  3390. ``` markdown
  3391. ***strong emph***
  3392. ***strong** in emph*
  3393. ***emph* in strong**
  3394. **in strong *emph***
  3395. *in emph **strong***
  3396. ```
  3397. The following patterns are less widely supported, but the intent
  3398. is clear and they are useful (especially in contexts like bibliography
  3399. entries):
  3400. ``` markdown
  3401. *emph *with emph* in it*
  3402. **strong **with strong** in it**
  3403. ```
  3404. Many implementations have also restricted intraword emphasis to
  3405. the `*` forms, to avoid unwanted emphasis in words containing
  3406. internal underscores. (It is best practice to put these in code
  3407. spans, but users often do not.)
  3408. ``` markdown
  3409. internal emphasis: foo*bar*baz
  3410. no emphasis: foo_bar_baz
  3411. ```
  3412. The following rules capture all of these patterns, while allowing
  3413. for efficient parsing strategies that do not backtrack:
  3414. 1. A single `*` character [can open emphasis](#can-open-emphasis)
  3415. <a id="can-open-emphasis"></a> iff
  3416. (a) it is not part of a sequence of four or more unescaped `*`s,
  3417. (b) it is not followed by whitespace, and
  3418. (c) either it is not followed by a `*` character or it is
  3419. followed immediately by emphasis or strong emphasis.
  3420. 2. A single `_` character [can open emphasis](#can-open-emphasis) iff
  3421. (a) it is not part of a sequence of four or more unescaped `_`s,
  3422. (b) it is not followed by whitespace,
  3423. (c) it is not preceded by an ASCII alphanumeric character, and
  3424. (d) either it is not followed by a `_` character or it is
  3425. followed immediately by emphasis or strong emphasis.
  3426. 3. A single `*` character [can close emphasis](#can-close-emphasis)
  3427. <a id="can-close-emphasis"></a> iff
  3428. (a) it is not part of a sequence of four or more unescaped `*`s, and
  3429. (b) it is not preceded by whitespace.
  3430. 4. A single `_` character [can close emphasis](#can-close-emphasis) iff
  3431. (a) it is not part of a sequence of four or more unescaped `_`s,
  3432. (b) it is not preceded by whitespace, and
  3433. (c) it is not followed by an ASCII alphanumeric character.
  3434. 5. A double `**` [can open strong emphasis](#can-open-strong-emphasis)
  3435. <a id="can-open-strong-emphasis" ></a> iff
  3436. (a) it is not part of a sequence of four or more unescaped `*`s,
  3437. (b) it is not followed by whitespace, and
  3438. (c) either it is not followed by a `*` character or it is
  3439. followed immediately by emphasis.
  3440. 6. A double `__` [can open strong emphasis](#can-open-strong-emphasis)
  3441. iff
  3442. (a) it is not part of a sequence of four or more unescaped `_`s,
  3443. (b) it is not followed by whitespace, and
  3444. (c) it is not preceded by an ASCII alphanumeric character, and
  3445. (d) either it is not followed by a `_` character or it is
  3446. followed immediately by emphasis.
  3447. 7. A double `**` [can close strong emphasis](#can-close-strong-emphasis)
  3448. <a id="can-close-strong-emphasis" ></a> iff
  3449. (a) it is not part of a sequence of four or more unescaped `*`s, and
  3450. (b) it is not preceded by whitespace.
  3451. 8. A double `__` [can close strong emphasis](#can-close-strong-emphasis)
  3452. iff
  3453. (a) it is not part of a sequence of four or more unescaped `_`s,
  3454. (b) it is not preceded by whitespace, and
  3455. (c) it is not followed by an ASCII alphanumeric character.
  3456. 9. Emphasis begins with a delimiter that [can open
  3457. emphasis](#can-open-emphasis) and ends with a delimiter that [can close
  3458. emphasis](#can-close-emphasis), and that uses the same
  3459. character (`_` or `*`) as the opening delimiter. The inlines
  3460. between the open delimiter and the closing delimiter are the
  3461. contents of the emphasis inline.
  3462. 10. Strong emphasis begins with a delimiter that [can open strong
  3463. emphasis](#can-open-strong-emphasis) and ends with a delimiter that
  3464. [can close strong emphasis](#can-close-strong-emphasis), and that uses the
  3465. same character (`_` or `*`) as the opening delimiter. The inlines
  3466. between the open delimiter and the closing delimiter are the
  3467. contents of the strong emphasis inline.
  3468. Where rules 1--10 above are compatible with multiple parsings,
  3469. the following principles resolve ambiguity:
  3470. 11. An interpretation `<strong>...</strong>` is always preferred to
  3471. `<em><em>...</em></em>`.
  3472. 12. An interpretation `<strong><em>...</em></strong>` is always
  3473. preferred to `<em><strong>..</strong></em>`.
  3474. 13. Earlier closings are preferred to later closings. Thus,
  3475. when two potential emphasis or strong emphasis spans overlap,
  3476. the first takes precedence: for example, `*foo _bar* baz_`
  3477. is parsed as `<em>foo _bar</em> baz_` rather than
  3478. `*foo <em>bar* baz</em>`. For the same reason,
  3479. `**foo*bar**` is parsed as `<em><em>foo</em>bar</em>*`
  3480. rather than `<strong>foo*bar</strong>`.
  3481. 14. Inline code spans, links, images, and HTML tags group more tightly
  3482. than emphasis. So, when there is a choice between an interpretation
  3483. that contains one of these elements and one that does not, the
  3484. former always wins. Thus, for example, `*[foo*](bar)` is
  3485. parsed as `*<a href="bar">foo*</a>` rather than as
  3486. `<em>[foo</em>](bar)`.
  3487. These rules can be illustrated through a series of examples.
  3488. Simple emphasis:
  3489. .
  3490. *foo bar*
  3491. .
  3492. <p><em>foo bar</em></p>
  3493. .
  3494. .
  3495. _foo bar_
  3496. .
  3497. <p><em>foo bar</em></p>
  3498. .
  3499. Simple strong emphasis:
  3500. .
  3501. **foo bar**
  3502. .
  3503. <p><strong>foo bar</strong></p>
  3504. .
  3505. .
  3506. __foo bar__
  3507. .
  3508. <p><strong>foo bar</strong></p>
  3509. .
  3510. Emphasis can continue over line breaks:
  3511. .
  3512. *foo
  3513. bar*
  3514. .
  3515. <p><em>foo
  3516. bar</em></p>
  3517. .
  3518. .
  3519. _foo
  3520. bar_
  3521. .
  3522. <p><em>foo
  3523. bar</em></p>
  3524. .
  3525. .
  3526. **foo
  3527. bar**
  3528. .
  3529. <p><strong>foo
  3530. bar</strong></p>
  3531. .
  3532. .
  3533. __foo
  3534. bar__
  3535. .
  3536. <p><strong>foo
  3537. bar</strong></p>
  3538. .
  3539. Emphasis can contain other inline constructs:
  3540. .
  3541. *foo [bar](/url)*
  3542. .
  3543. <p><em>foo <a href="/url">bar</a></em></p>
  3544. .
  3545. .
  3546. _foo [bar](/url)_
  3547. .
  3548. <p><em>foo <a href="/url">bar</a></em></p>
  3549. .
  3550. .
  3551. **foo [bar](/url)**
  3552. .
  3553. <p><strong>foo <a href="/url">bar</a></strong></p>
  3554. .
  3555. .
  3556. __foo [bar](/url)__
  3557. .
  3558. <p><strong>foo <a href="/url">bar</a></strong></p>
  3559. .
  3560. Symbols contained in other inline constructs will not
  3561. close emphasis:
  3562. .
  3563. *foo [bar*](/url)
  3564. .
  3565. <p>*foo <a href="/url">bar*</a></p>
  3566. .
  3567. .
  3568. _foo [bar_](/url)
  3569. .
  3570. <p>_foo <a href="/url">bar_</a></p>
  3571. .
  3572. .
  3573. **<a href="**">
  3574. .
  3575. <p>**<a href="**"></p>
  3576. .
  3577. .
  3578. __<a href="__">
  3579. .
  3580. <p>__<a href="__"></p>
  3581. .
  3582. .
  3583. *a `*`*
  3584. .
  3585. <p><em>a <code>*</code></em></p>
  3586. .
  3587. .
  3588. _a `_`_
  3589. .
  3590. <p><em>a <code>_</code></em></p>
  3591. .
  3592. .
  3593. **a<http://foo.bar?q=**>
  3594. .
  3595. <p>**a<a href="http://foo.bar?q=**">http://foo.bar?q=**</a></p>
  3596. .
  3597. .
  3598. __a<http://foo.bar?q=__>
  3599. .
  3600. <p>__a<a href="http://foo.bar?q=__">http://foo.bar?q=__</a></p>
  3601. .
  3602. This is not emphasis, because the opening delimiter is
  3603. followed by white space:
  3604. .
  3605. and * foo bar*
  3606. .
  3607. <p>and * foo bar*</p>
  3608. .
  3609. .
  3610. _ foo bar_
  3611. .
  3612. <p>_ foo bar_</p>
  3613. .
  3614. .
  3615. and ** foo bar**
  3616. .
  3617. <p>and ** foo bar**</p>
  3618. .
  3619. .
  3620. __ foo bar__
  3621. .
  3622. <p>__ foo bar__</p>
  3623. .
  3624. This is not emphasis, because the closing delimiter is
  3625. preceded by white space:
  3626. .
  3627. and *foo bar *
  3628. .
  3629. <p>and *foo bar *</p>
  3630. .
  3631. .
  3632. and _foo bar _
  3633. .
  3634. <p>and _foo bar _</p>
  3635. .
  3636. .
  3637. and **foo bar **
  3638. .
  3639. <p>and **foo bar **</p>
  3640. .
  3641. .
  3642. and __foo bar __
  3643. .
  3644. <p>and __foo bar __</p>
  3645. .
  3646. The rules imply that a sequence of four or more unescaped `*` or
  3647. `_` characters will always be parsed as a literal string:
  3648. .
  3649. ****hi****
  3650. .
  3651. <p>****hi****</p>
  3652. .
  3653. .
  3654. _____hi_____
  3655. .
  3656. <p>_____hi_____</p>
  3657. .
  3658. .
  3659. Sign here: _________
  3660. .
  3661. <p>Sign here: _________</p>
  3662. .
  3663. The rules also imply that there can be no empty emphasis or strong
  3664. emphasis:
  3665. .
  3666. ** is not an empty emphasis
  3667. .
  3668. <p>** is not an empty emphasis</p>
  3669. .
  3670. .
  3671. **** is not an empty strong emphasis
  3672. .
  3673. <p>**** is not an empty strong emphasis</p>
  3674. .
  3675. To include `*` or `_` in emphasized sections, use backslash escapes
  3676. or code spans:
  3677. .
  3678. *here is a \**
  3679. .
  3680. <p><em>here is a *</em></p>
  3681. .
  3682. .
  3683. __this is a double underscore (`__`)__
  3684. .
  3685. <p><strong>this is a double underscore (<code>__</code>)</strong></p>
  3686. .
  3687. Or use the other emphasis character:
  3688. .
  3689. *_*
  3690. .
  3691. <p><em>_</em></p>
  3692. .
  3693. .
  3694. _*_
  3695. .
  3696. <p><em>*</em></p>
  3697. .
  3698. .
  3699. *__*
  3700. .
  3701. <p><em>__</em></p>
  3702. .
  3703. .
  3704. _**_
  3705. .
  3706. <p><em>**</em></p>
  3707. .
  3708. `*` delimiters allow intra-word emphasis; `_` delimiters do not:
  3709. .
  3710. foo*bar*baz
  3711. .
  3712. <p>foo<em>bar</em>baz</p>
  3713. .
  3714. .
  3715. foo_bar_baz
  3716. .
  3717. <p>foo_bar_baz</p>
  3718. .
  3719. .
  3720. foo__bar__baz
  3721. .
  3722. <p>foo__bar__baz</p>
  3723. .
  3724. .
  3725. _foo_bar_baz_
  3726. .
  3727. <p><em>foo_bar_baz</em></p>
  3728. .
  3729. .
  3730. 11*15*32
  3731. .
  3732. <p>11<em>15</em>32</p>
  3733. .
  3734. .
  3735. 11_15_32
  3736. .
  3737. <p>11_15_32</p>
  3738. .
  3739. Internal underscores will be ignored in underscore-delimited
  3740. emphasis:
  3741. .
  3742. _foo_bar_baz_
  3743. .
  3744. <p><em>foo_bar_baz</em></p>
  3745. .
  3746. .
  3747. __foo__bar__baz__
  3748. .
  3749. <p><strong>foo__bar__baz</strong></p>
  3750. .
  3751. The rules are sufficient for the following nesting patterns:
  3752. .
  3753. ***foo bar***
  3754. .
  3755. <p><strong><em>foo bar</em></strong></p>
  3756. .
  3757. .
  3758. ___foo bar___
  3759. .
  3760. <p><strong><em>foo bar</em></strong></p>
  3761. .
  3762. .
  3763. ***foo** bar*
  3764. .
  3765. <p><em><strong>foo</strong> bar</em></p>
  3766. .
  3767. .
  3768. ___foo__ bar_
  3769. .
  3770. <p><em><strong>foo</strong> bar</em></p>
  3771. .
  3772. .
  3773. ***foo* bar**
  3774. .
  3775. <p><strong><em>foo</em> bar</strong></p>
  3776. .
  3777. .
  3778. ___foo_ bar__
  3779. .
  3780. <p><strong><em>foo</em> bar</strong></p>
  3781. .
  3782. .
  3783. *foo **bar***
  3784. .
  3785. <p><em>foo <strong>bar</strong></em></p>
  3786. .
  3787. .
  3788. _foo __bar___
  3789. .
  3790. <p><em>foo <strong>bar</strong></em></p>
  3791. .
  3792. .
  3793. **foo *bar***
  3794. .
  3795. <p><strong>foo <em>bar</em></strong></p>
  3796. .
  3797. .
  3798. __foo _bar___
  3799. .
  3800. <p><strong>foo <em>bar</em></strong></p>
  3801. .
  3802. .
  3803. *foo **bar***
  3804. .
  3805. <p><em>foo <strong>bar</strong></em></p>
  3806. .
  3807. .
  3808. _foo __bar___
  3809. .
  3810. <p><em>foo <strong>bar</strong></em></p>
  3811. .
  3812. .
  3813. *foo *bar* baz*
  3814. .
  3815. <p><em>foo <em>bar</em> baz</em></p>
  3816. .
  3817. .
  3818. _foo _bar_ baz_
  3819. .
  3820. <p><em>foo <em>bar</em> baz</em></p>
  3821. .
  3822. .
  3823. **foo **bar** baz**
  3824. .
  3825. <p><strong>foo <strong>bar</strong> baz</strong></p>
  3826. .
  3827. .
  3828. __foo __bar__ baz__
  3829. .
  3830. <p><strong>foo <strong>bar</strong> baz</strong></p>
  3831. .
  3832. .
  3833. *foo **bar** baz*
  3834. .
  3835. <p><em>foo <strong>bar</strong> baz</em></p>
  3836. .
  3837. .
  3838. _foo __bar__ baz_
  3839. .
  3840. <p><em>foo <strong>bar</strong> baz</em></p>
  3841. .
  3842. .
  3843. **foo *bar* baz**
  3844. .
  3845. <p><strong>foo <em>bar</em> baz</strong></p>
  3846. .
  3847. .
  3848. __foo _bar_ baz__
  3849. .
  3850. <p><strong>foo <em>bar</em> baz</strong></p>
  3851. .
  3852. .
  3853. **foo, *bar*, baz**
  3854. .
  3855. <p><strong>foo, <em>bar</em>, baz</strong></p>
  3856. .
  3857. .
  3858. __foo, _bar_, baz__
  3859. .
  3860. <p><strong>foo, <em>bar</em>, baz</strong></p>
  3861. .
  3862. But note:
  3863. .
  3864. *foo**bar**baz*
  3865. .
  3866. <p><em>foo</em><em>bar</em><em>baz</em></p>
  3867. .
  3868. .
  3869. **foo*bar*baz**
  3870. .
  3871. <p><em><em>foo</em>bar</em>baz**</p>
  3872. .
  3873. The difference is that in the two preceding cases,
  3874. the internal delimiters [can close emphasis](#can-close-emphasis),
  3875. while in the cases with spaces, they cannot.
  3876. Note that you cannot nest emphasis directly inside emphasis
  3877. using the same delimeter, or strong emphasis directly inside
  3878. strong emphasis:
  3879. .
  3880. **foo**
  3881. .
  3882. <p><strong>foo</strong></p>
  3883. .
  3884. .
  3885. ****foo****
  3886. .
  3887. <p>****foo****</p>
  3888. .
  3889. For these nestings, you need to switch delimiters:
  3890. .
  3891. *_foo_*
  3892. .
  3893. <p><em><em>foo</em></em></p>
  3894. .
  3895. .
  3896. **__foo__**
  3897. .
  3898. <p><strong><strong>foo</strong></strong></p>
  3899. .
  3900. Note that a `*` followed by a `*` can close emphasis, and
  3901. a `**` followed by a `*` can close strong emphasis (and
  3902. similarly for `_` and `__`):
  3903. .
  3904. *foo**
  3905. .
  3906. <p><em>foo</em>*</p>
  3907. .
  3908. .
  3909. *foo *bar**
  3910. .
  3911. <p><em>foo <em>bar</em></em></p>
  3912. .
  3913. .
  3914. **foo***
  3915. .
  3916. <p><strong>foo</strong>*</p>
  3917. .
  3918. .
  3919. ***foo* bar***
  3920. .
  3921. <p><strong><em>foo</em> bar</strong>*</p>
  3922. .
  3923. .
  3924. ***foo** bar***
  3925. .
  3926. <p><em><strong>foo</strong> bar</em>**</p>
  3927. .
  3928. The following contains no strong emphasis, because the opening
  3929. delimiter is closed by the first `*` before `bar`:
  3930. .
  3931. *foo**bar***
  3932. .
  3933. <p><em>foo</em><em>bar</em>**</p>
  3934. .
  3935. However, a string of four or more `****` can never close emphasis:
  3936. .
  3937. *foo****
  3938. .
  3939. <p>*foo****</p>
  3940. .
  3941. We retain symmetry in these cases:
  3942. .
  3943. *foo**
  3944. **foo*
  3945. .
  3946. <p><em>foo</em>*</p>
  3947. <p>*<em>foo</em></p>
  3948. .
  3949. .
  3950. *foo *bar**
  3951. **foo* bar*
  3952. .
  3953. <p><em>foo <em>bar</em></em></p>
  3954. <p><em><em>foo</em> bar</em></p>
  3955. .
  3956. More cases with mismatched delimiters:
  3957. .
  3958. *bar***
  3959. .
  3960. <p><em>bar</em>**</p>
  3961. .
  3962. .
  3963. ***foo*
  3964. .
  3965. <p>**<em>foo</em></p>
  3966. .
  3967. .
  3968. **bar***
  3969. .
  3970. <p><strong>bar</strong>*</p>
  3971. .
  3972. .
  3973. ***foo**
  3974. .
  3975. <p>*<strong>foo</strong></p>
  3976. .
  3977. .
  3978. ***foo *bar*
  3979. .
  3980. <p>***foo <em>bar</em></p>
  3981. .
  3982. The following cases illustrate rule 13:
  3983. .
  3984. *foo _bar* baz_
  3985. .
  3986. <p><em>foo _bar</em> baz_</p>
  3987. .
  3988. .
  3989. **foo bar* baz**
  3990. .
  3991. <p><em><em>foo bar</em> baz</em>*</p>
  3992. .
  3993. The following cases illustrate rule 14:
  3994. .
  3995. *[foo*](bar)
  3996. .
  3997. <p>*<a href="bar">foo*</a></p>
  3998. .
  3999. .
  4000. *![foo*](bar)
  4001. .
  4002. <p>*<img src="bar" alt="foo*" /></p>
  4003. .
  4004. .
  4005. *<img src="foo" title="*"/>
  4006. .
  4007. <p>*<img src="foo" title="*"/></p>
  4008. .
  4009. .
  4010. *a`a*`
  4011. .
  4012. <p>*a<code>a*</code></p>
  4013. .
  4014. ## Links
  4015. A link contains a [link label](#link-label) (the visible text),
  4016. a [destination](#destination) (the URI that is the link destination),
  4017. and optionally a [link title](#link-title). There are two basic kinds
  4018. of links in Markdown. In [inline links](#inline-links) the destination
  4019. and title are given immediately after the label. In [reference
  4020. links](#reference-links) the destination and title are defined elsewhere
  4021. in the document.
  4022. A [link label](#link-label) <a id="link-label"></a> consists of
  4023. - an opening `[`, followed by
  4024. - zero or more backtick code spans, autolinks, HTML tags, link labels,
  4025. backslash-escaped ASCII punctuation characters, or non-`]` characters,
  4026. followed by
  4027. - a closing `]`.
  4028. These rules are motivated by the following intuitive ideas:
  4029. - A link label is a container for inline elements.
  4030. - The square brackets bind more tightly than emphasis markers,
  4031. but less tightly than `<>` or `` ` ``.
  4032. - Link labels may contain material in matching square brackets.
  4033. A [link destination](#link-destination) <a id="link-destination"></a>
  4034. consists of either
  4035. - a sequence of zero or more characters between an opening `<` and a
  4036. closing `>` that contains no line breaks or unescaped `<` or `>`
  4037. characters, or
  4038. - a nonempty sequence of characters that does not include
  4039. ASCII space or control characters, and includes parentheses
  4040. only if (a) they are backslash-escaped or (b) they are part of
  4041. a balanced pair of unescaped parentheses that is not itself
  4042. inside a balanced pair of unescaped paretheses.
  4043. A [link title](#link-title) <a id="link-title"></a> consists of either
  4044. - a sequence of zero or more characters between straight double-quote
  4045. characters (`"`), including a `"` character only if it is
  4046. backslash-escaped, or
  4047. - a sequence of zero or more characters between straight single-quote
  4048. characters (`'`), including a `'` character only if it is
  4049. backslash-escaped, or
  4050. - a sequence of zero or more characters between matching parentheses
  4051. (`(...)`), including a `)` character only if it is backslash-escaped.
  4052. An [inline link](#inline-link) <a id="inline-link"></a>
  4053. consists of a [link label](#link-label) followed immediately
  4054. by a left parenthesis `(`, optional whitespace,
  4055. an optional [link destination](#link-destination),
  4056. an optional [link title](#link-title) separated from the link
  4057. destination by whitespace, optional whitespace, and a right
  4058. parenthesis `)`. The link's text consists of the label (excluding
  4059. the enclosing square brackets) parsed as inlines. The link's
  4060. URI consists of the link destination, excluding enclosing `<...>` if
  4061. present, with backslash-escapes in effect as described above. The
  4062. link's title consists of the link title, excluding its enclosing
  4063. delimiters, with backslash-escapes in effect as described above.
  4064. Here is a simple inline link:
  4065. .
  4066. [link](/uri "title")
  4067. .
  4068. <p><a href="/uri" title="title">link</a></p>
  4069. .
  4070. The title may be omitted:
  4071. .
  4072. [link](/uri)
  4073. .
  4074. <p><a href="/uri">link</a></p>
  4075. .
  4076. Both the title and the destination may be omitted:
  4077. .
  4078. [link]()
  4079. .
  4080. <p><a href="">link</a></p>
  4081. .
  4082. .
  4083. [link](<>)
  4084. .
  4085. <p><a href="">link</a></p>
  4086. .
  4087. If the destination contains spaces, it must be enclosed in pointy
  4088. braces:
  4089. .
  4090. [link](/my uri)
  4091. .
  4092. <p>[link](/my uri)</p>
  4093. .
  4094. .
  4095. [link](</my uri>)
  4096. .
  4097. <p><a href="/my%20uri">link</a></p>
  4098. .
  4099. The destination cannot contain line breaks, even with pointy braces:
  4100. .
  4101. [link](foo
  4102. bar)
  4103. .
  4104. <p>[link](foo
  4105. bar)</p>
  4106. .
  4107. One level of balanced parentheses is allowed without escaping:
  4108. .
  4109. [link]((foo)and(bar))
  4110. .
  4111. <p><a href="(foo)and(bar)">link</a></p>
  4112. .
  4113. However, if you have parentheses within parentheses, you need to escape
  4114. or use the `<...>` form:
  4115. .
  4116. [link](foo(and(bar)))
  4117. .
  4118. <p>[link](foo(and(bar)))</p>
  4119. .
  4120. .
  4121. [link](foo(and\(bar\)))
  4122. .
  4123. <p><a href="foo(and(bar))">link</a></p>
  4124. .
  4125. .
  4126. [link](<foo(and(bar))>)
  4127. .
  4128. <p><a href="foo(and(bar))">link</a></p>
  4129. .
  4130. Parentheses and other symbols can also be escaped, as usual
  4131. in Markdown:
  4132. .
  4133. [link](foo\)\:)
  4134. .
  4135. <p><a href="foo):">link</a></p>
  4136. .
  4137. URL-escaping should be left alone inside the destination, as all
  4138. URL-escaped characters are also valid URL characters. HTML entities in
  4139. the destination will be parsed into their UTF-8 codepoints, as usual, and
  4140. optionally URL-escaped when written as HTML.
  4141. .
  4142. [link](foo%20b&auml;)
  4143. .
  4144. <p><a href="foo%20b%C3%A4">link</a></p>
  4145. .
  4146. Note that, because titles can often be parsed as destinations,
  4147. if you try to omit the destination and keep the title, you'll
  4148. get unexpected results:
  4149. .
  4150. [link]("title")
  4151. .
  4152. <p><a href="%22title%22">link</a></p>
  4153. .
  4154. Titles may be in single quotes, double quotes, or parentheses:
  4155. .
  4156. [link](/url "title")
  4157. [link](/url 'title')
  4158. [link](/url (title))
  4159. .
  4160. <p><a href="/url" title="title">link</a>
  4161. <a href="/url" title="title">link</a>
  4162. <a href="/url" title="title">link</a></p>
  4163. .
  4164. Backslash escapes and entities may be used in titles:
  4165. .
  4166. [link](/url "title \"&quot;")
  4167. .
  4168. <p><a href="/url" title="title &quot;&quot;">link</a></p>
  4169. .
  4170. Nested balanced quotes are not allowed without escaping:
  4171. .
  4172. [link](/url "title "and" title")
  4173. .
  4174. <p>[link](/url &quot;title &quot;and&quot; title&quot;)</p>
  4175. .
  4176. But it is easy to work around this by using a different quote type:
  4177. .
  4178. [link](/url 'title "and" title')
  4179. .
  4180. <p><a href="/url" title="title &quot;and&quot; title">link</a></p>
  4181. .
  4182. (Note: `Markdown.pl` did allow double quotes inside a double-quoted
  4183. title, and its test suite included a test demonstrating this.
  4184. But it is hard to see a good rationale for the extra complexity this
  4185. brings, since there are already many ways---backslash escaping,
  4186. entities, or using a different quote type for the enclosing title---to
  4187. write titles containing double quotes. `Markdown.pl`'s handling of
  4188. titles has a number of other strange features. For example, it allows
  4189. single-quoted titles in inline links, but not reference links. And, in
  4190. reference links but not inline links, it allows a title to begin with
  4191. `"` and end with `)`. `Markdown.pl` 1.0.1 even allows titles with no closing
  4192. quotation mark, though 1.0.2b8 does not. It seems preferable to adopt
  4193. a simple, rational rule that works the same way in inline links and
  4194. link reference definitions.)
  4195. Whitespace is allowed around the destination and title:
  4196. .
  4197. [link]( /uri
  4198. "title" )
  4199. .
  4200. <p><a href="/uri" title="title">link</a></p>
  4201. .
  4202. But it is not allowed between the link label and the
  4203. following parenthesis:
  4204. .
  4205. [link] (/uri)
  4206. .
  4207. <p>[link] (/uri)</p>
  4208. .
  4209. Note that this is not a link, because the closing `]` occurs in
  4210. an HTML tag:
  4211. .
  4212. [foo <bar attr="](baz)">
  4213. .
  4214. <p>[foo <bar attr="](baz)"></p>
  4215. .
  4216. There are three kinds of [reference links](#reference-link):
  4217. <a id="reference-link"></a>
  4218. A [full reference link](#full-reference-link) <a id="full-reference-link"></a>
  4219. consists of a [link label](#link-label), optional whitespace, and
  4220. another [link label](#link-label) that [matches](#matches) a
  4221. [link reference definition](#link-reference-definition) elsewhere in the
  4222. document.
  4223. One label [matches](#matches) <a id="matches"></a>
  4224. another just in case their normalized forms are equal. To normalize a
  4225. label, perform the *unicode case fold* and collapse consecutive internal
  4226. whitespace to a single space. If there are multiple matching reference
  4227. link definitions, the one that comes first in the document is used. (It
  4228. is desirable in such cases to emit a warning.)
  4229. The contents of the first link label are parsed as inlines, which are
  4230. used as the link's text. The link's URI and title are provided by the
  4231. matching [link reference definition](#link-reference-definition).
  4232. Here is a simple example:
  4233. .
  4234. [foo][bar]
  4235. [bar]: /url "title"
  4236. .
  4237. <p><a href="/url" title="title">foo</a></p>
  4238. .
  4239. The first label can contain inline content:
  4240. .
  4241. [*foo\!*][bar]
  4242. [bar]: /url "title"
  4243. .
  4244. <p><a href="/url" title="title"><em>foo!</em></a></p>
  4245. .
  4246. Matching is case-insensitive:
  4247. .
  4248. [foo][BaR]
  4249. [bar]: /url "title"
  4250. .
  4251. <p><a href="/url" title="title">foo</a></p>
  4252. .
  4253. Unicode case fold is used:
  4254. .
  4255. [Толпой][Толпой] is a Russian word.
  4256. [ТОЛПОЙ]: /url
  4257. .
  4258. <p><a href="/url">Толпой</a> is a Russian word.</p>
  4259. .
  4260. Consecutive internal whitespace is treated as one space for
  4261. purposes of determining matching:
  4262. .
  4263. [Foo
  4264. bar]: /url
  4265. [Baz][Foo bar]
  4266. .
  4267. <p><a href="/url">Baz</a></p>
  4268. .
  4269. There can be whitespace between the two labels:
  4270. .
  4271. [foo] [bar]
  4272. [bar]: /url "title"
  4273. .
  4274. <p><a href="/url" title="title">foo</a></p>
  4275. .
  4276. .
  4277. [foo]
  4278. [bar]
  4279. [bar]: /url "title"
  4280. .
  4281. <p><a href="/url" title="title">foo</a></p>
  4282. .
  4283. When there are multiple matching [link reference
  4284. definitions](#link-reference-definition), the first is used:
  4285. .
  4286. [foo]: /url1
  4287. [foo]: /url2
  4288. [bar][foo]
  4289. .
  4290. <p><a href="/url1">bar</a></p>
  4291. .
  4292. Note that matching is performed on normalized strings, not parsed
  4293. inline content. So the following does not match, even though the
  4294. labels define equivalent inline content:
  4295. .
  4296. [bar][foo\!]
  4297. [foo!]: /url
  4298. .
  4299. <p>[bar][foo!]</p>
  4300. .
  4301. A [collapsed reference link](#collapsed-reference-link)
  4302. <a id="collapsed-reference-link"></a> consists of a [link
  4303. label](#link-label) that [matches](#matches) a [link reference
  4304. definition](#link-reference-definition) elsewhere in the
  4305. document, optional whitespace, and the string `[]`. The contents of the
  4306. first link label are parsed as inlines, which are used as the link's
  4307. text. The link's URI and title are provided by the matching reference
  4308. link definition. Thus, `[foo][]` is equivalent to `[foo][foo]`.
  4309. .
  4310. [foo][]
  4311. [foo]: /url "title"
  4312. .
  4313. <p><a href="/url" title="title">foo</a></p>
  4314. .
  4315. .
  4316. [*foo* bar][]
  4317. [*foo* bar]: /url "title"
  4318. .
  4319. <p><a href="/url" title="title"><em>foo</em> bar</a></p>
  4320. .
  4321. The link labels are case-insensitive:
  4322. .
  4323. [Foo][]
  4324. [foo]: /url "title"
  4325. .
  4326. <p><a href="/url" title="title">Foo</a></p>
  4327. .
  4328. As with full reference links, whitespace is allowed
  4329. between the two sets of brackets:
  4330. .
  4331. [foo]
  4332. []
  4333. [foo]: /url "title"
  4334. .
  4335. <p><a href="/url" title="title">foo</a></p>
  4336. .
  4337. A [shortcut reference link](#shortcut-reference-link)
  4338. <a id="shortcut-reference-link"></a> consists of a [link
  4339. label](#link-label) that [matches](#matches) a [link reference
  4340. definition](#link-reference-definition) elsewhere in the
  4341. document and is not followed by `[]` or a link label.
  4342. The contents of the first link label are parsed as inlines,
  4343. which are used as the link's text. the link's URI and title
  4344. are provided by the matching link reference definition.
  4345. Thus, `[foo]` is equivalent to `[foo][]`.
  4346. .
  4347. [foo]
  4348. [foo]: /url "title"
  4349. .
  4350. <p><a href="/url" title="title">foo</a></p>
  4351. .
  4352. .
  4353. [*foo* bar]
  4354. [*foo* bar]: /url "title"
  4355. .
  4356. <p><a href="/url" title="title"><em>foo</em> bar</a></p>
  4357. .
  4358. .
  4359. [[*foo* bar]]
  4360. [*foo* bar]: /url "title"
  4361. .
  4362. <p>[<a href="/url" title="title"><em>foo</em> bar</a>]</p>
  4363. .
  4364. The link labels are case-insensitive:
  4365. .
  4366. [Foo]
  4367. [foo]: /url "title"
  4368. .
  4369. <p><a href="/url" title="title">Foo</a></p>
  4370. .
  4371. If you just want bracketed text, you can backslash-escape the
  4372. opening bracket to avoid links:
  4373. .
  4374. \[foo]
  4375. [foo]: /url "title"
  4376. .
  4377. <p>[foo]</p>
  4378. .
  4379. Note that this is a link, because link labels bind more tightly
  4380. than emphasis:
  4381. .
  4382. [foo*]: /url
  4383. *[foo*]
  4384. .
  4385. <p>*<a href="/url">foo*</a></p>
  4386. .
  4387. However, this is not, because link labels bind less
  4388. tightly than code backticks:
  4389. .
  4390. [foo`]: /url
  4391. [foo`]`
  4392. .
  4393. <p>[foo<code>]</code></p>
  4394. .
  4395. Link labels can contain matched square brackets:
  4396. .
  4397. [[[foo]]]
  4398. [[[foo]]]: /url
  4399. .
  4400. <p><a href="/url">[[foo]]</a></p>
  4401. .
  4402. .
  4403. [[[foo]]]
  4404. [[[foo]]]: /url1
  4405. [foo]: /url2
  4406. .
  4407. <p><a href="/url1">[[foo]]</a></p>
  4408. .
  4409. For non-matching brackets, use backslash escapes:
  4410. .
  4411. [\[foo]
  4412. [\[foo]: /url
  4413. .
  4414. <p><a href="/url">[foo</a></p>
  4415. .
  4416. Full references take precedence over shortcut references:
  4417. .
  4418. [foo][bar]
  4419. [foo]: /url1
  4420. [bar]: /url2
  4421. .
  4422. <p><a href="/url2">foo</a></p>
  4423. .
  4424. In the following case `[bar][baz]` is parsed as a reference,
  4425. `[foo]` as normal text:
  4426. .
  4427. [foo][bar][baz]
  4428. [baz]: /url
  4429. .
  4430. <p>[foo]<a href="/url">bar</a></p>
  4431. .
  4432. Here, though, `[foo][bar]` is parsed as a reference, since
  4433. `[bar]` is defined:
  4434. .
  4435. [foo][bar][baz]
  4436. [baz]: /url1
  4437. [bar]: /url2
  4438. .
  4439. <p><a href="/url2">foo</a><a href="/url1">baz</a></p>
  4440. .
  4441. Here `[foo]` is not parsed as a shortcut reference, because it
  4442. is followed by a link label (even though `[bar]` is not defined):
  4443. .
  4444. [foo][bar][baz]
  4445. [baz]: /url1
  4446. [foo]: /url2
  4447. .
  4448. <p>[foo]<a href="/url1">bar</a></p>
  4449. .
  4450. ## Images
  4451. An (unescaped) exclamation mark (`!`) followed by a reference or
  4452. inline link will be parsed as an image. The link label will be
  4453. used as the image's alt text, and the link title, if any, will
  4454. be used as the image's title.
  4455. .
  4456. ![foo](/url "title")
  4457. .
  4458. <p><img src="/url" alt="foo" title="title" /></p>
  4459. .
  4460. .
  4461. ![foo *bar*]
  4462. [foo *bar*]: train.jpg "train & tracks"
  4463. .
  4464. <p><img src="train.jpg" alt="foo &lt;em&gt;bar&lt;/em&gt;" title="train &amp; tracks" /></p>
  4465. .
  4466. .
  4467. ![foo *bar*][]
  4468. [foo *bar*]: train.jpg "train & tracks"
  4469. .
  4470. <p><img src="train.jpg" alt="foo &lt;em&gt;bar&lt;/em&gt;" title="train &amp; tracks" /></p>
  4471. .
  4472. .
  4473. ![foo *bar*][foobar]
  4474. [FOOBAR]: train.jpg "train & tracks"
  4475. .
  4476. <p><img src="train.jpg" alt="foo &lt;em&gt;bar&lt;/em&gt;" title="train &amp; tracks" /></p>
  4477. .
  4478. .
  4479. ![foo](train.jpg)
  4480. .
  4481. <p><img src="train.jpg" alt="foo" /></p>
  4482. .
  4483. .
  4484. My ![foo bar](/path/to/train.jpg "title" )
  4485. .
  4486. <p>My <img src="/path/to/train.jpg" alt="foo bar" title="title" /></p>
  4487. .
  4488. .
  4489. ![foo](<url>)
  4490. .
  4491. <p><img src="url" alt="foo" /></p>
  4492. .
  4493. .
  4494. ![](/url)
  4495. .
  4496. <p><img src="/url" alt="" /></p>
  4497. .
  4498. Reference-style:
  4499. .
  4500. ![foo] [bar]
  4501. [bar]: /url
  4502. .
  4503. <p><img src="/url" alt="foo" /></p>
  4504. .
  4505. .
  4506. ![foo] [bar]
  4507. [BAR]: /url
  4508. .
  4509. <p><img src="/url" alt="foo" /></p>
  4510. .
  4511. Collapsed:
  4512. .
  4513. ![foo][]
  4514. [foo]: /url "title"
  4515. .
  4516. <p><img src="/url" alt="foo" title="title" /></p>
  4517. .
  4518. .
  4519. ![*foo* bar][]
  4520. [*foo* bar]: /url "title"
  4521. .
  4522. <p><img src="/url" alt="&lt;em&gt;foo&lt;/em&gt; bar" title="title" /></p>
  4523. .
  4524. The labels are case-insensitive:
  4525. .
  4526. ![Foo][]
  4527. [foo]: /url "title"
  4528. .
  4529. <p><img src="/url" alt="Foo" title="title" /></p>
  4530. .
  4531. As with full reference links, whitespace is allowed
  4532. between the two sets of brackets:
  4533. .
  4534. ![foo]
  4535. []
  4536. [foo]: /url "title"
  4537. .
  4538. <p><img src="/url" alt="foo" title="title" /></p>
  4539. .
  4540. Shortcut:
  4541. .
  4542. ![foo]
  4543. [foo]: /url "title"
  4544. .
  4545. <p><img src="/url" alt="foo" title="title" /></p>
  4546. .
  4547. .
  4548. ![*foo* bar]
  4549. [*foo* bar]: /url "title"
  4550. .
  4551. <p><img src="/url" alt="&lt;em&gt;foo&lt;/em&gt; bar" title="title" /></p>
  4552. .
  4553. .
  4554. ![[foo]]
  4555. [[foo]]: /url "title"
  4556. .
  4557. <p><img src="/url" alt="[foo]" title="title" /></p>
  4558. .
  4559. The link labels are case-insensitive:
  4560. .
  4561. ![Foo]
  4562. [foo]: /url "title"
  4563. .
  4564. <p><img src="/url" alt="Foo" title="title" /></p>
  4565. .
  4566. If you just want bracketed text, you can backslash-escape the
  4567. opening `!` and `[`:
  4568. .
  4569. \!\[foo]
  4570. [foo]: /url "title"
  4571. .
  4572. <p>![foo]</p>
  4573. .
  4574. If you want a link after a literal `!`, backslash-escape the
  4575. `!`:
  4576. .
  4577. \![foo]
  4578. [foo]: /url "title"
  4579. .
  4580. <p>!<a href="/url" title="title">foo</a></p>
  4581. .
  4582. ## Autolinks
  4583. Autolinks are absolute URIs and email addresses inside `<` and `>`.
  4584. They are parsed as links, with the URL or email address as the link
  4585. label.
  4586. A [URI autolink](#uri-autolink) <a id="uri-autolink"></a>
  4587. consists of `<`, followed by an [absolute
  4588. URI](#absolute-uri) not containing `<`, followed by `>`. It is parsed
  4589. as a link to the URI, with the URI as the link's label.
  4590. An [absolute URI](#absolute-uri), <a id="absolute-uri"></a>
  4591. for these purposes, consists of a [scheme](#scheme) followed by a colon (`:`)
  4592. followed by zero or more characters other than ASCII whitespace and
  4593. control characters, `<`, and `>`. If the URI includes these characters,
  4594. you must use percent-encoding (e.g. `%20` for a space).
  4595. The following [schemes](#scheme) <a id="scheme"></a>
  4596. are recognized (case-insensitive):
  4597. `coap`, `doi`, `javascript`, `aaa`, `aaas`, `about`, `acap`, `cap`,
  4598. `cid`, `crid`, `data`, `dav`, `dict`, `dns`, `file`, `ftp`, `geo`, `go`,
  4599. `gopher`, `h323`, `http`, `https`, `iax`, `icap`, `im`, `imap`, `info`,
  4600. `ipp`, `iris`, `iris.beep`, `iris.xpc`, `iris.xpcs`, `iris.lwz`, `ldap`,
  4601. `mailto`, `mid`, `msrp`, `msrps`, `mtqp`, `mupdate`, `news`, `nfs`,
  4602. `ni`, `nih`, `nntp`, `opaquelocktoken`, `pop`, `pres`, `rtsp`,
  4603. `service`, `session`, `shttp`, `sieve`, `sip`, `sips`, `sms`, `snmp`,`
  4604. soap.beep`, `soap.beeps`, `tag`, `tel`, `telnet`, `tftp`, `thismessage`,
  4605. `tn3270`, `tip`, `tv`, `urn`, `vemmi`, `ws`, `wss`, `xcon`,
  4606. `xcon-userid`, `xmlrpc.beep`, `xmlrpc.beeps`, `xmpp`, `z39.50r`,
  4607. `z39.50s`, `adiumxtra`, `afp`, `afs`, `aim`, `apt`,` attachment`, `aw`,
  4608. `beshare`, `bitcoin`, `bolo`, `callto`, `chrome`,` chrome-extension`,
  4609. `com-eventbrite-attendee`, `content`, `cvs`,` dlna-playsingle`,
  4610. `dlna-playcontainer`, `dtn`, `dvb`, `ed2k`, `facetime`, `feed`,
  4611. `finger`, `fish`, `gg`, `git`, `gizmoproject`, `gtalk`, `hcp`, `icon`,
  4612. `ipn`, `irc`, `irc6`, `ircs`, `itms`, `jar`, `jms`, `keyparc`, `lastfm`,
  4613. `ldaps`, `magnet`, `maps`, `market`,` message`, `mms`, `ms-help`,
  4614. `msnim`, `mumble`, `mvn`, `notes`, `oid`, `palm`, `paparazzi`,
  4615. `platform`, `proxy`, `psyc`, `query`, `res`, `resource`, `rmi`, `rsync`,
  4616. `rtmp`, `secondlife`, `sftp`, `sgn`, `skype`, `smb`, `soldat`,
  4617. `spotify`, `ssh`, `steam`, `svn`, `teamspeak`, `things`, `udp`,
  4618. `unreal`, `ut2004`, `ventrilo`, `view-source`, `webcal`, `wtai`,
  4619. `wyciwyg`, `xfire`, `xri`, `ymsgr`.
  4620. Here are some valid autolinks:
  4621. .
  4622. <http://foo.bar.baz>
  4623. .
  4624. <p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p>
  4625. .
  4626. .
  4627. <http://foo.bar.baz?q=hello&id=22&boolean>
  4628. .
  4629. <p><a href="http://foo.bar.baz?q=hello&amp;id=22&amp;boolean">http://foo.bar.baz?q=hello&amp;id=22&amp;boolean</a></p>
  4630. .
  4631. .
  4632. <irc://foo.bar:2233/baz>
  4633. .
  4634. <p><a href="irc://foo.bar:2233/baz">irc://foo.bar:2233/baz</a></p>
  4635. .
  4636. Uppercase is also fine:
  4637. .
  4638. <MAILTO:FOO@BAR.BAZ>
  4639. .
  4640. <p><a href="MAILTO:FOO@BAR.BAZ">MAILTO:FOO@BAR.BAZ</a></p>
  4641. .
  4642. Spaces are not allowed in autolinks:
  4643. .
  4644. <http://foo.bar/baz bim>
  4645. .
  4646. <p>&lt;http://foo.bar/baz bim&gt;</p>
  4647. .
  4648. An [email autolink](#email-autolink) <a id="email-autolink"></a>
  4649. consists of `<`, followed by an [email address](#email-address),
  4650. followed by `>`. The link's label is the email address,
  4651. and the URL is `mailto:` followed by the email address.
  4652. An [email address](#email-address), <a id="email-address"></a>
  4653. for these purposes, is anything that matches
  4654. the [non-normative regex from the HTML5
  4655. spec](http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#e-mail-state-%28type=email%29):
  4656. /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?
  4657. (?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/
  4658. Examples of email autolinks:
  4659. .
  4660. <foo@bar.example.com>
  4661. .
  4662. <p><a href="mailto:foo@bar.example.com">foo@bar.example.com</a></p>
  4663. .
  4664. .
  4665. <foo+special@Bar.baz-bar0.com>
  4666. .
  4667. <p><a href="mailto:foo+special@Bar.baz-bar0.com">foo+special@Bar.baz-bar0.com</a></p>
  4668. .
  4669. These are not autolinks:
  4670. .
  4671. <>
  4672. .
  4673. <p>&lt;&gt;</p>
  4674. .
  4675. .
  4676. <heck://bing.bong>
  4677. .
  4678. <p>&lt;heck://bing.bong&gt;</p>
  4679. .
  4680. .
  4681. < http://foo.bar >
  4682. .
  4683. <p>&lt; http://foo.bar &gt;</p>
  4684. .
  4685. .
  4686. <foo.bar.baz>
  4687. .
  4688. <p>&lt;foo.bar.baz&gt;</p>
  4689. .
  4690. .
  4691. <localhost:5001/foo>
  4692. .
  4693. <p>&lt;localhost:5001/foo&gt;</p>
  4694. .
  4695. .
  4696. http://example.com
  4697. .
  4698. <p>http://example.com</p>
  4699. .
  4700. .
  4701. foo@bar.example.com
  4702. .
  4703. <p>foo@bar.example.com</p>
  4704. .
  4705. ## Raw HTML
  4706. Text between `<` and `>` that looks like an HTML tag is parsed as a
  4707. raw HTML tag and will be rendered in HTML without escaping.
  4708. Tag and attribute names are not limited to current HTML tags,
  4709. so custom tags (and even, say, DocBook tags) may be used.
  4710. Here is the grammar for tags:
  4711. A [tag name](#tag-name) <a id="tag-name"></a> consists of an ASCII letter
  4712. followed by zero or more ASCII letters or digits.
  4713. An [attribute](#attribute) <a id="attribute"></a> consists of whitespace,
  4714. an **attribute name**, and an optional **attribute value
  4715. specification**.
  4716. An [attribute name](#attribute-name) <a id="attribute-name"></a>
  4717. consists of an ASCII letter, `_`, or `:`, followed by zero or more ASCII
  4718. letters, digits, `_`, `.`, `:`, or `-`. (Note: This is the XML
  4719. specification restricted to ASCII. HTML5 is laxer.)
  4720. An [attribute value specification](#attribute-value-specification)
  4721. <a id="attribute-value-specification"></a> consists of optional whitespace,
  4722. a `=` character, optional whitespace, and an [attribute
  4723. value](#attribute-value).
  4724. An [attribute value](#attribute-value) <a id="attribute-value"></a>
  4725. consists of an [unquoted attribute value](#unquoted-attribute-value),
  4726. a [single-quoted attribute value](#single-quoted-attribute-value),
  4727. or a [double-quoted attribute value](#double-quoted-attribute-value).
  4728. An [unquoted attribute value](#unquoted-attribute-value)
  4729. <a id="unquoted-attribute-value"></a> is a nonempty string of characters not
  4730. including spaces, `"`, `'`, `=`, `<`, `>`, or `` ` ``.
  4731. A [single-quoted attribute value](#single-quoted-attribute-value)
  4732. <a id="single-quoted-attribute-value"></a> consists of `'`, zero or more
  4733. characters not including `'`, and a final `'`.
  4734. A [double-quoted attribute value](#double-quoted-attribute-value)
  4735. <a id="double-quoted-attribute-value"></a> consists of `"`, zero or more
  4736. characters not including `"`, and a final `"`.
  4737. An [open tag](#open-tag) <a id="open-tag"></a> consists of a `<` character,
  4738. a [tag name](#tag-name), zero or more [attributes](#attribute),
  4739. optional whitespace, an optional `/` character, and a `>` character.
  4740. A [closing tag](#closing-tag) <a id="closing-tag"></a> consists of the
  4741. string `</`, a [tag name](#tag-name), optional whitespace, and the
  4742. character `>`.
  4743. An [HTML comment](#html-comment) <a id="html-comment"></a> consists of the
  4744. string `<!--`, a string of characters not including the string `--`, and
  4745. the string `-->`.
  4746. A [processing instruction](#processing-instruction)
  4747. <a id="processing-instruction"></a> consists of the string `<?`, a string
  4748. of characters not including the string `?>`, and the string
  4749. `?>`.
  4750. A [declaration](#declaration) <a id="declaration"></a> consists of the
  4751. string `<!`, a name consisting of one or more uppercase ASCII letters,
  4752. whitespace, a string of characters not including the character `>`, and
  4753. the character `>`.
  4754. A [CDATA section](#cdata-section) <a id="cdata-section"></a> consists of
  4755. the string `<![CDATA[`, a string of characters not including the string
  4756. `]]>`, and the string `]]>`.
  4757. An [HTML tag](#html-tag) <a id="html-tag"></a> consists of an [open
  4758. tag](#open-tag), a [closing tag](#closing-tag), an [HTML
  4759. comment](#html-comment), a [processing
  4760. instruction](#processing-instruction), an [element type
  4761. declaration](#element-type-declaration), or a [CDATA
  4762. section](#cdata-section).
  4763. Here are some simple open tags:
  4764. .
  4765. <a><bab><c2c>
  4766. .
  4767. <p><a><bab><c2c></p>
  4768. .
  4769. Empty elements:
  4770. .
  4771. <a/><b2/>
  4772. .
  4773. <p><a/><b2/></p>
  4774. .
  4775. Whitespace is allowed:
  4776. .
  4777. <a /><b2
  4778. data="foo" >
  4779. .
  4780. <p><a /><b2
  4781. data="foo" ></p>
  4782. .
  4783. With attributes:
  4784. .
  4785. <a foo="bar" bam = 'baz <em>"</em>'
  4786. _boolean zoop:33=zoop:33 />
  4787. .
  4788. <p><a foo="bar" bam = 'baz <em>"</em>'
  4789. _boolean zoop:33=zoop:33 /></p>
  4790. .
  4791. Illegal tag names, not parsed as HTML:
  4792. .
  4793. <33> <__>
  4794. .
  4795. <p>&lt;33&gt; &lt;__&gt;</p>
  4796. .
  4797. Illegal attribute names:
  4798. .
  4799. <a h*#ref="hi">
  4800. .
  4801. <p>&lt;a h*#ref=&quot;hi&quot;&gt;</p>
  4802. .
  4803. Illegal attribute values:
  4804. .
  4805. <a href="hi'> <a href=hi'>
  4806. .
  4807. <p>&lt;a href=&quot;hi'&gt; &lt;a href=hi'&gt;</p>
  4808. .
  4809. Illegal whitespace:
  4810. .
  4811. < a><
  4812. foo><bar/ >
  4813. .
  4814. <p>&lt; a&gt;&lt;
  4815. foo&gt;&lt;bar/ &gt;</p>
  4816. .
  4817. Missing whitespace:
  4818. .
  4819. <a href='bar'title=title>
  4820. .
  4821. <p>&lt;a href='bar'title=title&gt;</p>
  4822. .
  4823. Closing tags:
  4824. .
  4825. </a>
  4826. </foo >
  4827. .
  4828. <p></a>
  4829. </foo ></p>
  4830. .
  4831. Illegal attributes in closing tag:
  4832. .
  4833. </a href="foo">
  4834. .
  4835. <p>&lt;/a href=&quot;foo&quot;&gt;</p>
  4836. .
  4837. Comments:
  4838. .
  4839. foo <!-- this is a
  4840. comment - with hyphen -->
  4841. .
  4842. <p>foo <!-- this is a
  4843. comment - with hyphen --></p>
  4844. .
  4845. .
  4846. foo <!-- not a comment -- two hyphens -->
  4847. .
  4848. <p>foo &lt;!-- not a comment -- two hyphens --&gt;</p>
  4849. .
  4850. Processing instructions:
  4851. .
  4852. foo <?php echo $a; ?>
  4853. .
  4854. <p>foo <?php echo $a; ?></p>
  4855. .
  4856. Declarations:
  4857. .
  4858. foo <!ELEMENT br EMPTY>
  4859. .
  4860. <p>foo <!ELEMENT br EMPTY></p>
  4861. .
  4862. CDATA sections:
  4863. .
  4864. foo <![CDATA[>&<]]>
  4865. .
  4866. <p>foo <![CDATA[>&<]]></p>
  4867. .
  4868. Entities are preserved in HTML attributes:
  4869. .
  4870. <a href="&ouml;">
  4871. .
  4872. <p><a href="&ouml;"></p>
  4873. .
  4874. Backslash escapes do not work in HTML attributes:
  4875. .
  4876. <a href="\*">
  4877. .
  4878. <p><a href="\*"></p>
  4879. .
  4880. .
  4881. <a href="\"">
  4882. .
  4883. <p>&lt;a href=&quot;&quot;&quot;&gt;</p>
  4884. .
  4885. ## Hard line breaks
  4886. A line break (not in a code span or HTML tag) that is preceded
  4887. by two or more spaces is parsed as a [hard line
  4888. break](#hard-line-break)<a id="hard-line-break"></a> (rendered
  4889. in HTML as a `<br />` tag):
  4890. .
  4891. foo
  4892. baz
  4893. .
  4894. <p>foo<br />
  4895. baz</p>
  4896. .
  4897. For a more visible alternative, a backslash before the newline may be
  4898. used instead of two spaces:
  4899. .
  4900. foo\
  4901. baz
  4902. .
  4903. <p>foo<br />
  4904. baz</p>
  4905. .
  4906. More than two spaces can be used:
  4907. .
  4908. foo
  4909. baz
  4910. .
  4911. <p>foo<br />
  4912. baz</p>
  4913. .
  4914. Leading spaces at the beginning of the next line are ignored:
  4915. .
  4916. foo
  4917. bar
  4918. .
  4919. <p>foo<br />
  4920. bar</p>
  4921. .
  4922. .
  4923. foo\
  4924. bar
  4925. .
  4926. <p>foo<br />
  4927. bar</p>
  4928. .
  4929. Line breaks can occur inside emphasis, links, and other constructs
  4930. that allow inline content:
  4931. .
  4932. *foo
  4933. bar*
  4934. .
  4935. <p><em>foo<br />
  4936. bar</em></p>
  4937. .
  4938. .
  4939. *foo\
  4940. bar*
  4941. .
  4942. <p><em>foo<br />
  4943. bar</em></p>
  4944. .
  4945. Line breaks do not occur inside code spans
  4946. .
  4947. `code
  4948. span`
  4949. .
  4950. <p><code>code span</code></p>
  4951. .
  4952. .
  4953. `code\
  4954. span`
  4955. .
  4956. <p><code>code\ span</code></p>
  4957. .
  4958. or HTML tags:
  4959. .
  4960. <a href="foo
  4961. bar">
  4962. .
  4963. <p><a href="foo
  4964. bar"></p>
  4965. .
  4966. .
  4967. <a href="foo\
  4968. bar">
  4969. .
  4970. <p><a href="foo\
  4971. bar"></p>
  4972. .
  4973. ## Soft line breaks
  4974. A regular line break (not in a code span or HTML tag) that is not
  4975. preceded by two or more spaces is parsed as a softbreak. (A
  4976. softbreak may be rendered in HTML either as a newline or as a space.
  4977. The result will be the same in browsers. In the examples here, a
  4978. newline will be used.)
  4979. .
  4980. foo
  4981. baz
  4982. .
  4983. <p>foo
  4984. baz</p>
  4985. .
  4986. Spaces at the end of the line and beginning of the next line are
  4987. removed:
  4988. .
  4989. foo
  4990. baz
  4991. .
  4992. <p>foo
  4993. baz</p>
  4994. .
  4995. A conforming parser may render a soft line break in HTML either as a
  4996. line break or as a space.
  4997. A renderer may also provide an option to render soft line breaks
  4998. as hard line breaks.
  4999. ## Strings
  5000. Any characters not given an interpretation by the above rules will
  5001. be parsed as string content.
  5002. .
  5003. hello $.;'there
  5004. .
  5005. <p>hello $.;'there</p>
  5006. .
  5007. .
  5008. Foo χρῆν
  5009. .
  5010. <p>Foo χρῆν</p>
  5011. .
  5012. Internal spaces are preserved verbatim:
  5013. .
  5014. Multiple spaces
  5015. .
  5016. <p>Multiple spaces</p>
  5017. .
  5018. <!-- END TESTS -->
  5019. # Appendix A: A parsing strategy {-}
  5020. ## Overview {-}
  5021. Parsing has two phases:
  5022. 1. In the first phase, lines of input are consumed and the block
  5023. structure of the document---its division into paragraphs, block quotes,
  5024. list items, and so on---is constructed. Text is assigned to these
  5025. blocks but not parsed. Link reference definitions are parsed and a
  5026. map of links is constructed.
  5027. 2. In the second phase, the raw text contents of paragraphs and headers
  5028. are parsed into sequences of Markdown inline elements (strings,
  5029. code spans, links, emphasis, and so on), using the map of link
  5030. references constructed in phase 1.
  5031. ## The document tree {-}
  5032. At each point in processing, the document is represented as a tree of
  5033. **blocks**. The root of the tree is a `document` block. The `document`
  5034. may have any number of other blocks as **children**. These children
  5035. may, in turn, have other blocks as children. The last child of a block
  5036. is normally considered **open**, meaning that subsequent lines of input
  5037. can alter its contents. (Blocks that are not open are **closed**.)
  5038. Here, for example, is a possible document tree, with the open blocks
  5039. marked by arrows:
  5040. ``` tree
  5041. -> document
  5042. -> block_quote
  5043. paragraph
  5044. "Lorem ipsum dolor\nsit amet."
  5045. -> list (type=bullet tight=true bullet_char=-)
  5046. list_item
  5047. paragraph
  5048. "Qui *quodsi iracundia*"
  5049. -> list_item
  5050. -> paragraph
  5051. "aliquando id"
  5052. ```
  5053. ## How source lines alter the document tree {-}
  5054. Each line that is processed has an effect on this tree. The line is
  5055. analyzed and, depending on its contents, the document may be altered
  5056. in one or more of the following ways:
  5057. 1. One or more open blocks may be closed.
  5058. 2. One or more new blocks may be created as children of the
  5059. last open block.
  5060. 3. Text may be added to the last (deepest) open block remaining
  5061. on the tree.
  5062. Once a line has been incorporated into the tree in this way,
  5063. it can be discarded, so input can be read in a stream.
  5064. We can see how this works by considering how the tree above is
  5065. generated by four lines of Markdown:
  5066. ``` markdown
  5067. > Lorem ipsum dolor
  5068. sit amet.
  5069. > - Qui *quodsi iracundia*
  5070. > - aliquando id
  5071. ```
  5072. At the outset, our document model is just
  5073. ``` tree
  5074. -> document
  5075. ```
  5076. The first line of our text,
  5077. ``` markdown
  5078. > Lorem ipsum dolor
  5079. ```
  5080. causes a `block_quote` block to be created as a child of our
  5081. open `document` block, and a `paragraph` block as a child of
  5082. the `block_quote`. Then the text is added to the last open
  5083. block, the `paragraph`:
  5084. ``` tree
  5085. -> document
  5086. -> block_quote
  5087. -> paragraph
  5088. "Lorem ipsum dolor"
  5089. ```
  5090. The next line,
  5091. ``` markdown
  5092. sit amet.
  5093. ```
  5094. is a "lazy continuation" of the open `paragraph`, so it gets added
  5095. to the paragraph's text:
  5096. ``` tree
  5097. -> document
  5098. -> block_quote
  5099. -> paragraph
  5100. "Lorem ipsum dolor\nsit amet."
  5101. ```
  5102. The third line,
  5103. ``` markdown
  5104. > - Qui *quodsi iracundia*
  5105. ```
  5106. causes the `paragraph` block to be closed, and a new `list` block
  5107. opened as a child of the `block_quote`. A `list_item` is also
  5108. added as a child of the `list`, and a `paragraph` as a child of
  5109. the `list_item`. The text is then added to the new `paragraph`:
  5110. ``` tree
  5111. -> document
  5112. -> block_quote
  5113. paragraph
  5114. "Lorem ipsum dolor\nsit amet."
  5115. -> list (type=bullet tight=true bullet_char=-)
  5116. -> list_item
  5117. -> paragraph
  5118. "Qui *quodsi iracundia*"
  5119. ```
  5120. The fourth line,
  5121. ``` markdown
  5122. > - aliquando id
  5123. ```
  5124. causes the `list_item` (and its child the `paragraph`) to be closed,
  5125. and a new `list_item` opened up as child of the `list`. A `paragraph`
  5126. is added as a child of the new `list_item`, to contain the text.
  5127. We thus obtain the final tree:
  5128. ``` tree
  5129. -> document
  5130. -> block_quote
  5131. paragraph
  5132. "Lorem ipsum dolor\nsit amet."
  5133. -> list (type=bullet tight=true bullet_char=-)
  5134. list_item
  5135. paragraph
  5136. "Qui *quodsi iracundia*"
  5137. -> list_item
  5138. -> paragraph
  5139. "aliquando id"
  5140. ```
  5141. ## From block structure to the final document {-}
  5142. Once all of the input has been parsed, all open blocks are closed.
  5143. We then "walk the tree," visiting every node, and parse raw
  5144. string contents of paragraphs and headers as inlines. At this
  5145. point we have seen all the link reference definitions, so we can
  5146. resolve reference links as we go.
  5147. ``` tree
  5148. document
  5149. block_quote
  5150. paragraph
  5151. str "Lorem ipsum dolor"
  5152. softbreak
  5153. str "sit amet."
  5154. list (type=bullet tight=true bullet_char=-)
  5155. list_item
  5156. paragraph
  5157. str "Qui "
  5158. emph
  5159. str "quodsi iracundia"
  5160. list_item
  5161. paragraph
  5162. str "aliquando id"
  5163. ```
  5164. Notice how the newline in the first paragraph has been parsed as
  5165. a `softbreak`, and the asterisks in the first list item have become
  5166. an `emph`.
  5167. The document can be rendered as HTML, or in any other format, given
  5168. an appropriate renderer.