bar

+```````````````````````````````` + + + +A partial tag need not even be completed (garbage +in, garbage out): + +```````````````````````````````` example +

*foo*

+. +

*foo*

+```````````````````````````````` + + +```````````````````````````````` example +

+foo +

+. +

+foo +

+```````````````````````````````` + + +Everything until the next blank line or end of document +gets included in the HTML block. So, in the following +example, what looks like a Markdown code block +is actually part of the HTML block, which continues until a blank +line or the end of the document is reached: + +```````````````````````````````` example +

+``` c +int x = 33; +``` +. +

+``` c +int x = 33; +``` +```````````````````````````````` + + +To start an [HTML block] with a tag that is *not* in the +list of block-level tags in (6), you must put the tag by +itself on the first line (and it must be complete): + +```````````````````````````````` example + +*bar* + +. + +*bar* + +```````````````````````````````` + + +In type 7 blocks, the [tag name] can be anything: + +```````````````````````````````` example + +*bar* + +. + +*bar* + +```````````````````````````````` + + +```````````````````````````````` example + +*bar* + +. + +*bar* + +```````````````````````````````` + + +```````````````````````````````` example + +*bar* +. + +*bar* +```````````````````````````````` + + +These rules are designed to allow us to work with tags that +can function as either block-level or inline-level tags. +The `` tag is a nice example. We can surround content with +`` tags in three different ways. In this case, we get a raw +HTML block, because the `` tag is on a line by itself: + +```````````````````````````````` example + ~~+*foo* +~~ +. + ~~+*foo* +~~ +```````````````````````````````` + + +In this case, we get a raw HTML block that just includes +the `` tag (because it ends with the following blank +line). So the contents get interpreted as CommonMark: + +```````````````````````````````` example + ~~+ +*foo* + +~~ +. + +
foo
+ +```````````````````````````````` + + +Finally, in this case, the `` tags are interpreted +as [raw HTML] *inside* the CommonMark paragraph. (Because +the tag is not on a line by itself, we get inline HTML +rather than an [HTML block].) + +```````````````````````````````` example +~~*foo*~~ +. +
~~foo~~
+```````````````````````````````` + + +HTML tags designed to contain literal content +(`pre`, `script`, `style`, `textarea`), comments, processing instructions, +and declarations are treated somewhat differently. +Instead of ending at the first blank line, these blocks +end at the first line containing a corresponding end tag. +As a result, these blocks can contain blank lines: + +A pre tag (type 1): + +```````````````````````````````` example +
+import Text.HTML.TagSoup + +main :: IO () +main = print $ parseTags tags +
+okay +. +
+import Text.HTML.TagSoup + +main :: IO () +main = print $ parseTags tags +
+
okay
+```````````````````````````````` + + +A script tag (type 1): + +```````````````````````````````` example + +okay +. + +
okay
+```````````````````````````````` + + +A textarea tag (type 1): + +```````````````````````````````` example ++ +*foo* + +_bar_ + + +. ++ +*foo* + +_bar_ + + +```````````````````````````````` + +A style tag (type 1): + +```````````````````````````````` example + +okay +. + +
okay
+```````````````````````````````` + + +If there is no matching end tag, the block will end at the +end of the document (or the enclosing [block quote][block quotes] +or [list item][list items]): + +```````````````````````````````` example + +*foo* +. + +
foo
+```````````````````````````````` + + +```````````````````````````````` example +*bar* +*baz* +. +*bar* +
baz
+```````````````````````````````` + + +Note that anything on the last line after the +end tag will be included in the [HTML block]: + +```````````````````````````````` example +1. *bar* +. +1. *bar* +```````````````````````````````` + + +A comment (type 2): + +```````````````````````````````` example + +okay +. + +
okay
+```````````````````````````````` + + + +A processing instruction (type 3): + +```````````````````````````````` example +'; + +?> +okay +. +'; + +?> +
okay
+```````````````````````````````` + + +A declaration (type 4): + +```````````````````````````````` example + +. + +```````````````````````````````` + + +CDATA (type 5): + +```````````````````````````````` example + +okay +. + +
okay
+```````````````````````````````` + + +The opening tag can be preceded by up to three spaces of indentation, but not +four: + +```````````````````````````````` example + + + +. + +
 +
+```````````````````````````````` + + +```````````````````````````````` example +
+ +
+. +
+
<div> +
+```````````````````````````````` + + +An HTML block of types 1--6 can interrupt a paragraph, and need not be +preceded by a blank line. + +```````````````````````````````` example +Foo +
+bar +
+. +
Foo
+
+bar +
+```````````````````````````````` + + +However, a following blank line is needed, except at the end of +a document, and except for blocks of types 1--5, [above][HTML +block]: + +```````````````````````````````` example +
+bar +
+*foo* +. +
+bar +
+*foo* +```````````````````````````````` + + +HTML blocks of type 7 cannot interrupt a paragraph: + +```````````````````````````````` example +Foo + +baz +. +
Foo + +baz
+```````````````````````````````` + + +This rule differs from John Gruber's original Markdown syntax +specification, which says: + +> The only restrictions are that block-level HTML elements — +> e.g. `
`, ``, `
`, `
`, etc. — must be separated from +> surrounding content by blank lines, and the start and end tags of the +> block should not be indented with spaces or tabs. + +In some ways Gruber's rule is more restrictive than the one given +here: + +- It requires that an HTML block be preceded by a blank line. +- It does not allow the start tag to be indented. +- It requires a matching end tag, which it also does not allow to + be indented. + +Most Markdown implementations (including some of Gruber's own) do not +respect all of these restrictions. + +There is one respect, however, in which Gruber's rule is more liberal +than the one given here, since it allows blank lines to occur inside +an HTML block. There are two reasons for disallowing them here. +First, it removes the need to parse balanced tags, which is +expensive and can require backtracking from the end of the document +if no matching end tag is found. Second, it provides a very simple +and flexible way of including Markdown content inside HTML tags: +simply separate the Markdown from the HTML using blank lines: + +Compare: + +```````````````````````````````` example +
+ +*Emphasized* text. + +
+. +
+
Emphasized text.
+
+```````````````````````````````` + + +```````````````````````````````` example +
+*Emphasized* text. +
+. +
+*Emphasized* text. +
+```````````````````````````````` + + +Some Markdown implementations have adopted a convention of +interpreting content inside tags as text if the open tag has +the attribute `markdown=1`. The rule given above seems a simpler and +more elegant way of achieving the same expressive power, which is also +much simpler to parse. + +The main potential drawback is that one can no longer paste HTML +blocks into Markdown documents with 100% reliability. However, +*in most cases* this will work fine, because the blank lines in +HTML are usually followed by HTML block tags. For example: + +```````````````````````````````` example +
+ + + + + + + +
+Hi +
+. + + + + +
+Hi +
+```````````````````````````````` + + +There are problems, however, if the inner tags are indented +*and* separated by spaces, as then they will be interpreted as +an indented code block: + +```````````````````````````````` example + + + + + + + + +
+ Hi +
+. + + +
<td> + Hi +</td> +
+ +
+```````````````````````````````` + + +Fortunately, blank lines are usually not necessary and can be +deleted. The exception is inside `
` tags, but as described +[above][HTML blocks], raw HTML blocks starting with `
` +*can* contain blank lines. + +## Link reference definitions + +A [link reference definition](@) +consists of a [link label], optionally preceded by up to three spaces of +indentation, followed +by a colon (`:`), optional spaces or tabs (including up to one +[line ending]), a [link destination], +optional spaces or tabs (including up to one +[line ending]), and an optional [link +title], which if it is present must be separated +from the [link destination] by spaces or tabs. +No further character may occur. + +A [link reference definition] +does not correspond to a structural element of a document. Instead, it +defines a label which can be used in [reference links] +and reference-style [images] elsewhere in the document. [Link +reference definitions] can come either before or after the links that use +them. + +```````````````````````````````` example +[foo]: /url "title" + +[foo] +. +
foo
+```````````````````````````````` + + +```````````````````````````````` example + [foo]: + /url + 'the title' + +[foo] +. +
foo
+```````````````````````````````` + + +```````````````````````````````` example +[Foo*bar\]]:my_(url) 'title (with parens)' + +[Foo*bar\]] +. +
Foo*bar]
+```````````````````````````````` + + +```````````````````````````````` example +[Foo bar]: + +'title' + +[Foo bar] +. +
Foo bar
+```````````````````````````````` + + +The title may extend over multiple lines: + +```````````````````````````````` example +[foo]: /url ' +title +line1 +line2 +' + +[foo] +. +
foo
+```````````````````````````````` + + +However, it may not contain a [blank line]: + +```````````````````````````````` example +[foo]: /url 'title + +with blank line' + +[foo] +. +
[foo]: /url 'title
+
with blank line'
+
[foo]
+```````````````````````````````` + + +The title may be omitted: + +```````````````````````````````` example +[foo]: +/url + +[foo] +. +
foo
+```````````````````````````````` + + +The link destination may not be omitted: + +```````````````````````````````` example +[foo]: + +[foo] +. +
[foo]:
+
[foo]
+```````````````````````````````` + + However, an empty link destination may be specified using + angle brackets: + +```````````````````````````````` example +[foo]: <> + +[foo] +. +
foo
+```````````````````````````````` + +The title must be separated from the link destination by +spaces or tabs: + +```````````````````````````````` example +[foo]: (baz) + +[foo] +. +
[foo]: (baz)
+
[foo]
+```````````````````````````````` + + +Both title and destination can contain backslash escapes +and literal backslashes: + +```````````````````````````````` example +[foo]: /url\bar\*baz "foo\"bar\baz" + +[foo] +. +
foo
+```````````````````````````````` + + +A link can come before its corresponding definition: + +```````````````````````````````` example +[foo] + +[foo]: url +. +
foo
+```````````````````````````````` + + +If there are several matching definitions, the first one takes +precedence: + +```````````````````````````````` example +[foo] + +[foo]: first +[foo]: second +. +
foo
+```````````````````````````````` + + +As noted in the section on [Links], matching of labels is +case-insensitive (see [matches]). + +```````````````````````````````` example +[FOO]: /url + +[Foo] +. +
Foo
+```````````````````````````````` + + +```````````````````````````````` example +[ΑΓΩ]: /φου + +[αγω] +. +
αγω
+```````````````````````````````` + + +Whether something is a [link reference definition] is +independent of whether the link reference it defines is +used in the document. Thus, for example, the following +document contains just a link reference definition, and +no visible content: + +```````````````````````````````` example +[foo]: /url +. +```````````````````````````````` + + +Here is another one: + +```````````````````````````````` example +[ +foo +]: /url +bar +. +
bar
+```````````````````````````````` + + +This is not a link reference definition, because there are +characters other than spaces or tabs after the title: + +```````````````````````````````` example +[foo]: /url "title" ok +. +
[foo]: /url "title" ok
+```````````````````````````````` + + +This is a link reference definition, but it has no title: + +```````````````````````````````` example +[foo]: /url +"title" ok +. +
"title" ok
+```````````````````````````````` + + +This is not a link reference definition, because it is indented +four spaces: + +```````````````````````````````` example + [foo]: /url "title" + +[foo] +. +
[foo]: /url "title" +
+
[foo]
+```````````````````````````````` + + +This is not a link reference definition, because it occurs inside +a code block: + +```````````````````````````````` example +``` +[foo]: /url +``` + +[foo] +. +
[foo]: /url +
+
[foo]
+```````````````````````````````` + + +A [link reference definition] cannot interrupt a paragraph. + +```````````````````````````````` example +Foo +[bar]: /baz + +[bar] +. +
Foo +[bar]: /baz
+
[bar]
+```````````````````````````````` + + +However, it can directly follow other block elements, such as headings +and thematic breaks, and it need not be followed by a blank line. + +```````````````````````````````` example +# [Foo] +[foo]: /url +> bar +. +
Foo
+
+
bar
+
+```````````````````````````````` + +```````````````````````````````` example +[foo]: /url +bar +=== +[foo] +. +
bar
+
foo
+```````````````````````````````` + +```````````````````````````````` example +[foo]: /url +=== +[foo] +. +
=== +foo
+```````````````````````````````` + + +Several [link reference definitions] +can occur one after another, without intervening blank lines. + +```````````````````````````````` example +[foo]: /foo-url "foo" +[bar]: /bar-url + "bar" +[baz]: /baz-url + +[foo], +[bar], +[baz] +. +
foo, +bar, +baz
+```````````````````````````````` + + +[Link reference definitions] can occur +inside block containers, like lists and block quotations. They +affect the entire document, not just the container in which they +are defined: + +```````````````````````````````` example +[foo] + +> [foo]: /url +. +
foo
+
+
+```````````````````````````````` + + +## Paragraphs + +A sequence of non-blank lines that cannot be interpreted as other +kinds of blocks forms a [paragraph](@). +The contents of the paragraph are the result of parsing the +paragraph's raw content as inlines. The paragraph's raw content +is formed by concatenating the lines and removing initial and final +spaces or tabs. + +A simple example with two paragraphs: + +```````````````````````````````` example +aaa + +bbb +. +
aaa
+
bbb
+```````````````````````````````` + + +Paragraphs can contain multiple lines, but no blank lines: + +```````````````````````````````` example +aaa +bbb + +ccc +ddd +. +
aaa +bbb
+
ccc +ddd
+```````````````````````````````` + + +Multiple blank lines between paragraphs have no effect: + +```````````````````````````````` example +aaa + + +bbb +. +
aaa
+
bbb
+```````````````````````````````` + + +Leading spaces or tabs are skipped: + +```````````````````````````````` example + aaa + bbb +. +
aaa +bbb
+```````````````````````````````` + + +Lines after the first may be indented any amount, since indented +code blocks cannot interrupt paragraphs. + +```````````````````````````````` example +aaa + bbb + ccc +. +
aaa +bbb +ccc
+```````````````````````````````` + + +However, the first line may be preceded by up to three spaces of indentation. +Four spaces of indentation is too many: + +```````````````````````````````` example + aaa +bbb +. +
aaa +bbb
+```````````````````````````````` + + +```````````````````````````````` example + aaa +bbb +. +
aaa +
+
bbb
+```````````````````````````````` + + +Final spaces or tabs are stripped before inline parsing, so a paragraph +that ends with two or more spaces will not end with a [hard line +break]: + +```````````````````````````````` example +aaa +bbb +. +
aaa
+bbb
+```````````````````````````````` + + +## Blank lines + +[Blank lines] between block-level elements are ignored, +except for the role they play in determining whether a [list] +is [tight] or [loose]. + +Blank lines at the beginning and end of the document are also ignored. + +```````````````````````````````` example + + +aaa + + +# aaa + + +. +
aaa
+
aaa
+```````````````````````````````` + + + +# Container blocks + +A [container block](#container-blocks) is a block that has other +blocks as its contents. There are two basic kinds of container blocks: +[block quotes] and [list items]. +[Lists] are meta-containers for [list items]. + +We define the syntax for container blocks recursively. The general +form of the definition is: + +> If X is a sequence of blocks, then the result of +> transforming X in such-and-such a way is a container of type Y +> with these blocks as its content. + +So, we explain what counts as a block quote or list item by explaining +how these can be *generated* from their contents. This should suffice +to define the syntax, although it does not give a recipe for *parsing* +these constructions. (A recipe is provided below in the section entitled +[A parsing strategy](#appendix-a-parsing-strategy).) + +## Block quotes + +A [block quote marker](@), +optionally preceded by up to three spaces of indentation, +consists of (a) the character `>` together with a following space of +indentation, or (b) a single character `>` not followed by a space of +indentation. + +The following rules define [block quotes]: + +1. **Basic case.** If a string of lines *Ls* constitute a sequence + of blocks *Bs*, then the result of prepending a [block quote + marker] to the beginning of each line in *Ls* + is a [block quote](#block-quotes) containing *Bs*. + +2. **Laziness.** If a string of lines *Ls* constitute a [block + quote](#block-quotes) with contents *Bs*, then the result of deleting + the initial [block quote marker] from one or + more lines in which the next character other than a space or tab after the + [block quote marker] is [paragraph continuation + text] is a block quote with *Bs* as its content. + [Paragraph continuation text](@) is text + that will be parsed as part of the content of a paragraph, but does + not occur at the beginning of the paragraph. + +3. **Consecutiveness.** A document cannot contain two [block + quotes] in a row unless there is a [blank line] between them. + +Nothing else counts as a [block quote](#block-quotes). + +Here is a simple example: + +```````````````````````````````` example +> # Foo +> bar +> baz +. +
+
Foo
+
bar +baz
+
+```````````````````````````````` + + +The space or tab after the `>` characters can be omitted: + +```````````````````````````````` example +># Foo +>bar +> baz +. +
+
Foo
+
bar +baz
+
+```````````````````````````````` + + +The `>` characters can be preceded by up to three spaces of indentation: + +```````````````````````````````` example + > # Foo + > bar + > baz +. +
+
Foo
+
bar +baz
+
+```````````````````````````````` + + +Four spaces of indentation is too many: + +```````````````````````````````` example + > # Foo + > bar + > baz +. +
> # Foo +> bar +> baz +
+```````````````````````````````` + + +The Laziness clause allows us to omit the `>` before +[paragraph continuation text]: + +```````````````````````````````` example +> # Foo +> bar +baz +. +
+
Foo
+
bar +baz
+
+```````````````````````````````` + + +A block quote can contain some lazy and some non-lazy +continuation lines: + +```````````````````````````````` example +> bar +baz +> foo +. +
+
bar +baz +foo
+
+```````````````````````````````` + + +Laziness only applies to lines that would have been continuations of +paragraphs had they been prepended with [block quote markers]. +For example, the `> ` cannot be omitted in the second line of + +``` markdown +> foo +> --- +``` + +without changing the meaning: + +```````````````````````````````` example +> foo +--- +. +
+
foo
+
+
+```````````````````````````````` + + +Similarly, if we omit the `> ` in the second line of + +``` markdown +> - foo +> - bar +``` + +then the block quote ends after the first line: + +```````````````````````````````` example +> - foo +- bar +. +
+
+
foo
+
+
+
+
bar
+
+```````````````````````````````` + + +For the same reason, we can't omit the `> ` in front of +subsequent lines of an indented or fenced code block: + +```````````````````````````````` example +> foo + bar +. +
+
foo +
+
+
bar +
+```````````````````````````````` + + +```````````````````````````````` example +> ``` +foo +``` +. +
+
+
+
foo
+
+```````````````````````````````` + + +Note that in the following case, we have a [lazy +continuation line]: + +```````````````````````````````` example +> foo + - bar +. +
+
foo +- bar
+
+```````````````````````````````` + + +To see why, note that in + +```markdown +> foo +> - bar +``` + +the `- bar` is indented too far to start a list, and can't +be an indented code block because indented code blocks cannot +interrupt paragraphs, so it is [paragraph continuation text]. + +A block quote can be empty: + +```````````````````````````````` example +> +. +
+
+```````````````````````````````` + + +```````````````````````````````` example +> +> +> +. +
+
+```````````````````````````````` + + +A block quote can have initial or final blank lines: + +```````````````````````````````` example +> +> foo +> +. +
+
foo
+
+```````````````````````````````` + + +A blank line always separates block quotes: + +```````````````````````````````` example +> foo + +> bar +. +
+
foo
+
+
+
bar
+
+```````````````````````````````` + + +(Most current Markdown implementations, including John Gruber's +original `Markdown.pl`, will parse this example as a single block quote +with two paragraphs. But it seems better to allow the author to decide +whether two block quotes or one are wanted.) + +Consecutiveness means that if we put these block quotes together, +we get a single block quote: + +```````````````````````````````` example +> foo +> bar +. +
+
foo +bar
+
+```````````````````````````````` + + +To get a block quote with two paragraphs, use: + +```````````````````````````````` example +> foo +> +> bar +. +
+
foo
+
bar
+
+```````````````````````````````` + + +Block quotes can interrupt paragraphs: + +```````````````````````````````` example +foo +> bar +. +
foo
+
+
bar
+
+```````````````````````````````` + + +In general, blank lines are not needed before or after block +quotes: + +```````````````````````````````` example +> aaa +*** +> bbb +. +
+
aaa
+
+
+
+
bbb
+
+```````````````````````````````` + + +However, because of laziness, a blank line is needed between +a block quote and a following paragraph: + +```````````````````````````````` example +> bar +baz +. +
+
bar +baz
+
+```````````````````````````````` + + +```````````````````````````````` example +> bar + +baz +. +
+
bar
+
+
baz
+```````````````````````````````` + + +```````````````````````````````` example +> bar +> +baz +. +
+
bar
+
+
baz
+```````````````````````````````` + + +It is a consequence of the Laziness rule that any number +of initial `>`s may be omitted on a continuation line of a +nested block quote: + +```````````````````````````````` example +> > > foo +bar +. +
+
+
+
foo +bar
+
+
+
+```````````````````````````````` + + +```````````````````````````````` example +>>> foo +> bar +>>baz +. +
+
+
+
foo +bar +baz
+
+
+
+```````````````````````````````` + + +When including an indented code block in a block quote, +remember that the [block quote marker] includes +both the `>` and a following space of indentation. So *five spaces* are needed +after the `>`: + +```````````````````````````````` example +> code + +> not code +. +
+
code +
+
+
+
not code
+
+```````````````````````````````` + + + +## List items + +A [list marker](@) is a +[bullet list marker] or an [ordered list marker]. + +A [bullet list marker](@) +is a `-`, `+`, or `*` character. + +An [ordered list marker](@) +is a sequence of 1--9 arabic digits (`0-9`), followed by either a +`.` character or a `)` character. (The reason for the length +limit is that with 10 digits we start seeing integer overflows +in some browsers.) + +The following rules define [list items]: + +1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of + blocks *Bs* starting with a character other than a space or tab, and *M* is + a list marker of width *W* followed by 1 ≤ *N* ≤ 4 spaces of indentation, + then the result of prepending *M* and the following spaces to the first line + of Ls*, and indenting subsequent lines of *Ls* by *W + N* spaces, is a + list item with *Bs* as its contents. The type of the list item + (bullet or ordered) is determined by the type of its list marker. + If the list item is ordered, then it is also assigned a start + number, based on the ordered list marker. + + Exceptions: + + 1. When the first list item in a [list] interrupts + a paragraph---that is, when it starts on a line that would + otherwise count as [paragraph continuation text]---then (a) + the lines *Ls* must not begin with a blank line, and (b) if + the list item is ordered, the start number must be 1. + 2. If any line is a [thematic break][thematic breaks] then + that line is not a list item. + +For example, let *Ls* be the lines + +```````````````````````````````` example +A paragraph +with two lines. + + indented code + +> A block quote. +. +
A paragraph +with two lines.
+
indented code +
+
+
A block quote.
+
+```````````````````````````````` + + +And let *M* be the marker `1.`, and *N* = 2. Then rule #1 says +that the following is an ordered list item with start number 1, +and the same contents as *Ls*: + +```````````````````````````````` example +1. A paragraph + with two lines. + + indented code + + > A block quote. +. +
+
+
A paragraph +with two lines.
+
indented code +
+
+
A block quote.
+
+
+
+```````````````````````````````` + + +The most important thing to notice is that the position of +the text after the list marker determines how much indentation +is needed in subsequent blocks in the list item. If the list +marker takes up two spaces of indentation, and there are three spaces between +the list marker and the next character other than a space or tab, then blocks +must be indented five spaces in order to fall under the list +item. + +Here are some examples showing how far content must be indented to be +put under the list item: + +```````````````````````````````` example +- one + + two +. +
+
one
+
+
two
+```````````````````````````````` + + +```````````````````````````````` example +- one + + two +. +
+
+
one
+
two
+
+
+```````````````````````````````` + + +```````````````````````````````` example + - one + + two +. +
+
one
+
+
two +
+```````````````````````````````` + + +```````````````````````````````` example + - one + + two +. +
+
+
one
+
two
+
+
+```````````````````````````````` + + +It is tempting to think of this in terms of columns: the continuation +blocks must be indented at least to the column of the first character other than +a space or tab after the list marker. However, that is not quite right. +The spaces of indentation after the list marker determine how much relative +indentation is needed. Which column this indentation reaches will depend on +how the list item is embedded in other constructions, as shown by +this example: + +```````````````````````````````` example + > > 1. one +>> +>> two +. +
+
+
+
+
one
+
two
+
+
+
+
+```````````````````````````````` + + +Here `two` occurs in the same column as the list marker `1.`, +but is actually contained in the list item, because there is +sufficient indentation after the last containing blockquote marker. + +The converse is also possible. In the following example, the word `two` +occurs far to the right of the initial text of the list item, `one`, but +it is not considered part of the list item, because it is not indented +far enough past the blockquote marker: + +```````````````````````````````` example +>>- one +>> + > > two +. +
+
+
+
one
+
+
two
+
+
+```````````````````````````````` + + +Note that at least one space or tab is needed between the list marker and +any following content, so these are not list items: + +```````````````````````````````` example +-one + +2.two +. +
-one
+
2.two
+```````````````````````````````` + + +A list item may contain blocks that are separated by more than +one blank line. + +```````````````````````````````` example +- foo + + + bar +. +
+
+
foo
+
bar
+
+
+```````````````````````````````` + + +A list item may contain any kind of block: + +```````````````````````````````` example +1. foo + + ``` + bar + ``` + + baz + + > bam +. +
+
+
foo
+
bar +
+
baz
+
+
bam
+
+
+
+```````````````````````````````` + + +A list item that contains an indented code block will preserve +empty lines within the code block verbatim. + +```````````````````````````````` example +- Foo + + bar + + + baz +. +
+
+
Foo
+
bar + + +baz +
+
+
+```````````````````````````````` + +Note that ordered list start numbers must be nine digits or less: + +```````````````````````````````` example +123456789. ok +. +
+
ok
+
+```````````````````````````````` + + +```````````````````````````````` example +1234567890. not ok +. +
1234567890. not ok
+```````````````````````````````` + + +A start number may begin with 0s: + +```````````````````````````````` example +0. ok +. +
+
ok
+
+```````````````````````````````` + + +```````````````````````````````` example +003. ok +. +
+
ok
+
+```````````````````````````````` + + +A start number may not be negative: + +```````````````````````````````` example +-1. not ok +. +
-1. not ok
+```````````````````````````````` + + + +2. **Item starting with indented code.** If a sequence of lines *Ls* + constitute a sequence of blocks *Bs* starting with an indented code + block, and *M* is a list marker of width *W* followed by + one space of indentation, then the result of prepending *M* and the + following space to the first line of *Ls*, and indenting subsequent lines + of *Ls* by *W + 1* spaces, is a list item with *Bs* as its contents. + If a line is empty, then it need not be indented. The type of the + list item (bullet or ordered) is determined by the type of its list + marker. If the list item is ordered, then it is also assigned a + start number, based on the ordered list marker. + +An indented code block will have to be preceded by four spaces of indentation +beyond the edge of the region where text will be included in the list item. +In the following case that is 6 spaces: + +```````````````````````````````` example +- foo + + bar +. +
+
+
foo
+
bar +
+
+
+```````````````````````````````` + + +And in this case it is 11 spaces: + +```````````````````````````````` example + 10. foo + + bar +. +
+
+
foo
+
bar +
+
+
+```````````````````````````````` + + +If the *first* block in the list item is an indented code block, +then by rule #2, the contents must be preceded by *one* space of indentation +after the list marker: + +```````````````````````````````` example + indented code + +paragraph + + more code +. +
indented code +
+
paragraph
+
more code +
+```````````````````````````````` + + +```````````````````````````````` example +1. indented code + + paragraph + + more code +. +
+
+
indented code +
+
paragraph
+
more code +
+
+
+```````````````````````````````` + + +Note that an additional space of indentation is interpreted as space +inside the code block: + +```````````````````````````````` example +1. indented code + + paragraph + + more code +. +
+
+
indented code +
+
paragraph
+
more code +
+
+
+```````````````````````````````` + + +Note that rules #1 and #2 only apply to two cases: (a) cases +in which the lines to be included in a list item begin with a +characer other than a space or tab, and (b) cases in which +they begin with an indented code +block. In a case like the following, where the first block begins with +three spaces of indentation, the rules do not allow us to form a list item by +indenting the whole thing and prepending a list marker: + +```````````````````````````````` example + foo + +bar +. +
foo
+
bar
+```````````````````````````````` + + +```````````````````````````````` example +- foo + + bar +. +
+
foo
+
+
bar
+```````````````````````````````` + + +This is not a significant restriction, because when a block is preceded by up to +three spaces of indentation, the indentation can always be removed without +a change in interpretation, allowing rule #1 to be applied. So, in +the above case: + +```````````````````````````````` example +- foo + + bar +. +
+
+
foo
+
bar
+
+
+```````````````````````````````` + + +3. **Item starting with a blank line.** If a sequence of lines *Ls* + starting with a single [blank line] constitute a (possibly empty) + sequence of blocks *Bs*, and *M* is a list marker of width *W*, + then the result of prepending *M* to the first line of *Ls*, and + preceding subsequent lines of *Ls* by *W + 1* spaces of indentation, is a + list item with *Bs* as its contents. + If a line is empty, then it need not be indented. The type of the + list item (bullet or ordered) is determined by the type of its list + marker. If the list item is ordered, then it is also assigned a + start number, based on the ordered list marker. + +Here are some list items that start with a blank line but are not empty: + +```````````````````````````````` example +- + foo +- + ``` + bar + ``` +- + baz +. +
+
foo
+
+
bar +
+
+
+
baz +
+
+
+```````````````````````````````` + +When the list item starts with a blank line, the number of spaces +following the list marker doesn't change the required indentation: + +```````````````````````````````` example +- + foo +. +
+
foo
+
+```````````````````````````````` + + +A list item can begin with at most one blank line. +In the following example, `foo` is not part of the list +item: + +```````````````````````````````` example +- + + foo +. +
+
+
+
foo
+```````````````````````````````` + + +Here is an empty bullet list item: + +```````````````````````````````` example +- foo +- +- bar +. +
+
foo
+
+
bar
+
+```````````````````````````````` + + +It does not matter whether there are spaces or tabs following the [list marker]: + +```````````````````````````````` example +- foo +- +- bar +. +
+
foo
+
+
bar
+
+```````````````````````````````` + + +Here is an empty ordered list item: + +```````````````````````````````` example +1. foo +2. +3. bar +. +
+
foo
+
+
bar
+
+```````````````````````````````` + + +A list may start or end with an empty list item: + +```````````````````````````````` example +* +. +
+
+
+```````````````````````````````` + +However, an empty list item cannot interrupt a paragraph: + +```````````````````````````````` example +foo +* + +foo +1. +. +
foo +*
+
foo +1.
+```````````````````````````````` + + +4. **Indentation.** If a sequence of lines *Ls* constitutes a list item + according to rule #1, #2, or #3, then the result of preceding each line + of *Ls* by up to three spaces of indentation (the same for each line) also + constitutes a list item with the same contents and attributes. If a line is + empty, then it need not be indented. + +Indented one space: + +```````````````````````````````` example + 1. A paragraph + with two lines. + + indented code + + > A block quote. +. +
+
+
A paragraph +with two lines.
+
indented code +
+
+
A block quote.
+
+
+
+```````````````````````````````` + + +Indented two spaces: + +```````````````````````````````` example + 1. A paragraph + with two lines. + + indented code + + > A block quote. +. +
+
+
A paragraph +with two lines.
+
indented code +
+
+
A block quote.
+
+
+
+```````````````````````````````` + + +Indented three spaces: + +```````````````````````````````` example + 1. A paragraph + with two lines. + + indented code + + > A block quote. +. +
+
+
A paragraph +with two lines.
+
indented code +
+
+
A block quote.
+
+
+
+```````````````````````````````` + + +Four spaces indent gives a code block: + +```````````````````````````````` example + 1. A paragraph + with two lines. + + indented code + + > A block quote. +. +
1. A paragraph + with two lines. + + indented code + + > A block quote. +
+```````````````````````````````` + + + +5. **Laziness.** If a string of lines *Ls* constitute a [list + item](#list-items) with contents *Bs*, then the result of deleting + some or all of the indentation from one or more lines in which the + next character other than a space or tab after the indentation is + [paragraph continuation text] is a + list item with the same contents and attributes. The unindented + lines are called + [lazy continuation line](@)s. + +Here is an example with [lazy continuation lines]: + +```````````````````````````````` example + 1. A paragraph +with two lines. + + indented code + + > A block quote. +. +
+
+
A paragraph +with two lines.
+
indented code +
+
+
A block quote.
+
+
+
+```````````````````````````````` + + +Indentation can be partially deleted: + +```````````````````````````````` example + 1. A paragraph + with two lines. +. +
+
A paragraph +with two lines.
+
+```````````````````````````````` + + +These examples show how laziness can work in nested structures: + +```````````````````````````````` example +> 1. > Blockquote +continued here. +. +
+
+
+
+
Blockquote +continued here.
+
+
+
+
+```````````````````````````````` + + +```````````````````````````````` example +> 1. > Blockquote +> continued here. +. +
+
+
+
+
Blockquote +continued here.
+
+
+
+
+```````````````````````````````` + + + +6. **That's all.** Nothing that is not counted as a list item by rules + #1--5 counts as a [list item](#list-items). + +The rules for sublists follow from the general rules +[above][List items]. A sublist must be indented the same number +of spaces of indentation a paragraph would need to be in order to be included +in the list item. + +So, in this case we need two spaces indent: + +```````````````````````````````` example +- foo + - bar + - baz + - boo +. +
+
foo +
+
bar +
+
baz +
+
boo
+
+
+
+
+
+
+
+```````````````````````````````` + + +One is not enough: + +```````````````````````````````` example +- foo + - bar + - baz + - boo +. +
+
foo
+
bar
+
baz
+
boo
+
+```````````````````````````````` + + +Here we need four, because the list marker is wider: + +```````````````````````````````` example +10) foo + - bar +. +
+
foo +
+
bar
+
+
+
+```````````````````````````````` + + +Three is not enough: + +```````````````````````````````` example +10) foo + - bar +. +
+
foo
+
+
+
bar
+
+```````````````````````````````` + + +A list may be the first block in a list item: + +```````````````````````````````` example +- - foo +. +
+
+
+
foo
+
+
+
+```````````````````````````````` + + +```````````````````````````````` example +1. - 2. foo +. +
+
+
+
+
+
foo
+
+
+
+
+
+```````````````````````````````` + + +A list item can contain a heading: + +```````````````````````````````` example +- # Foo +- Bar + --- + baz +. +
+
+
Foo
+
+
+
Bar
+baz
+
+```````````````````````````````` + + +### Motivation + +John Gruber's Markdown spec says the following about list items: + +1. "List markers typically start at the left margin, but may be indented + by up to three spaces. List markers must be followed by one or more + spaces or a tab." + +2. "To make lists look nice, you can wrap items with hanging indents.... + But if you don't want to, you don't have to." + +3. "List items may consist of multiple paragraphs. Each subsequent + paragraph in a list item must be indented by either 4 spaces or one + tab." + +4. "It looks nice if you indent every line of the subsequent paragraphs, + but here again, Markdown will allow you to be lazy." + +5. "To put a blockquote within a list item, the blockquote's `>` + delimiters need to be indented." + +6. "To put a code block within a list item, the code block needs to be + indented twice — 8 spaces or two tabs." + +These rules specify that a paragraph under a list item must be indented +four spaces (presumably, from the left margin, rather than the start of +the list marker, but this is not said), and that code under a list item +must be indented eight spaces instead of the usual four. They also say +that a block quote must be indented, but not by how much; however, the +example given has four spaces indentation. Although nothing is said +about other kinds of block-level content, it is certainly reasonable to +infer that *all* block elements under a list item, including other +lists, must be indented four spaces. This principle has been called the +*four-space rule*. + +The four-space rule is clear and principled, and if the reference +implementation `Markdown.pl` had followed it, it probably would have +become the standard. However, `Markdown.pl` allowed paragraphs and +sublists to start with only two spaces indentation, at least on the +outer level. Worse, its behavior was inconsistent: a sublist of an +outer-level list needed two spaces indentation, but a sublist of this +sublist needed three spaces. It is not surprising, then, that different +implementations of Markdown have developed very different rules for +determining what comes under a list item. (Pandoc and python-Markdown, +for example, stuck with Gruber's syntax description and the four-space +rule, while discount, redcarpet, marked, PHP Markdown, and others +followed `Markdown.pl`'s behavior more closely.) + +Unfortunately, given the divergences between implementations, there +is no way to give a spec for list items that will be guaranteed not +to break any existing documents. However, the spec given here should +correctly handle lists formatted with either the four-space rule or +the more forgiving `Markdown.pl` behavior, provided they are laid out +in a way that is natural for a human to read. + +The strategy here is to let the width and indentation of the list marker +determine the indentation necessary for blocks to fall under the list +item, rather than having a fixed and arbitrary number. The writer can +think of the body of the list item as a unit which gets indented to the +right enough to fit the list marker (and any indentation on the list +marker). (The laziness rule, #5, then allows continuation lines to be +unindented if needed.) + +This rule is superior, we claim, to any rule requiring a fixed level of +indentation from the margin. The four-space rule is clear but +unnatural. It is quite unintuitive that + +``` markdown +- foo + + bar + + - baz +``` + +should be parsed as two lists with an intervening paragraph, + +``` html +
+
foo
+
+
bar
+
+
baz
+
+``` + +as the four-space rule demands, rather than a single list, + +``` html +
+
+
foo
+
bar
+
+
baz
+
+
+
+``` + +The choice of four spaces is arbitrary. It can be learned, but it is +not likely to be guessed, and it trips up beginners regularly. + +Would it help to adopt a two-space rule? The problem is that such +a rule, together with the rule allowing up to three spaces of indentation for +the initial list marker, allows text that is indented *less than* the +original list marker to be included in the list item. For example, +`Markdown.pl` parses + +``` markdown + - one + + two +``` + +as a single list item, with `two` a continuation paragraph: + +``` html +
+
+
one
+
two
+
+
+``` + +and similarly + +``` markdown +> - one +> +> two +``` + +as + +``` html +
+
+
+
one
+
two
+
+
+
+``` + +This is extremely unintuitive. + +Rather than requiring a fixed indent from the margin, we could require +a fixed indent (say, two spaces, or even one space) from the list marker (which +may itself be indented). This proposal would remove the last anomaly +discussed. Unlike the spec presented above, it would count the following +as a list item with a subparagraph, even though the paragraph `bar` +is not indented as far as the first paragraph `foo`: + +``` markdown + 10. foo + + bar +``` + +Arguably this text does read like a list item with `bar` as a subparagraph, +which may count in favor of the proposal. However, on this proposal indented +code would have to be indented six spaces after the list marker. And this +would break a lot of existing Markdown, which has the pattern: + +``` markdown +1. foo + + indented code +``` + +where the code is indented eight spaces. The spec above, by contrast, will +parse this text as expected, since the code block's indentation is measured +from the beginning of `foo`. + +The one case that needs special treatment is a list item that *starts* +with indented code. How much indentation is required in that case, since +we don't have a "first paragraph" to measure from? Rule #2 simply stipulates +that in such cases, we require one space indentation from the list marker +(and then the normal four spaces for the indented code). This will match the +four-space rule in cases where the list marker plus its initial indentation +takes four spaces (a common case), but diverge in other cases. + +## Lists + +A [list](@) is a sequence of one or more +list items [of the same type]. The list items +may be separated by any number of blank lines. + +Two list items are [of the same type](@) +if they begin with a [list marker] of the same type. +Two list markers are of the +same type if (a) they are bullet list markers using the same character +(`-`, `+`, or `*`) or (b) they are ordered list numbers with the same +delimiter (either `.` or `)`). + +A list is an [ordered list](@) +if its constituent list items begin with +[ordered list markers], and a +[bullet list](@) if its constituent list +items begin with [bullet list markers]. + +The [start number](@) +of an [ordered list] is determined by the list number of +its initial list item. The numbers of subsequent list items are +disregarded. + +A list is [loose](@) if any of its constituent +list items are separated by blank lines, or if any of its constituent +list items directly contain two block-level elements with a blank line +between them. Otherwise a list is [tight](@). +(The difference in HTML output is that paragraphs in a loose list are +wrapped in `
` tags, while paragraphs in a tight list are not.) + +Changing the bullet or ordered list delimiter starts a new list: + +```````````````````````````````` example +- foo +- bar ++ baz +. +
+
foo
+
bar
+
+
+
baz
+
+```````````````````````````````` + + +```````````````````````````````` example +1. foo +2. bar +3) baz +. +
+
foo
+
bar
+
+
+
baz
+
+```````````````````````````````` + + +In CommonMark, a list can interrupt a paragraph. That is, +no blank line is needed to separate a paragraph from a following +list: + +```````````````````````````````` example +Foo +- bar +- baz +. +
Foo
+
+
bar
+
baz
+
+```````````````````````````````` + +`Markdown.pl` does not allow this, through fear of triggering a list +via a numeral in a hard-wrapped line: + +``` markdown +The number of windows in my house is +14. The number of doors is 6. +``` + +Oddly, though, `Markdown.pl` *does* allow a blockquote to +interrupt a paragraph, even though the same considerations might +apply. + +In CommonMark, we do allow lists to interrupt paragraphs, for +two reasons. First, it is natural and not uncommon for people +to start lists without blank lines: + +``` markdown +I need to buy +- new shoes +- a coat +- a plane ticket +``` + +Second, we are attracted to a + +> [principle of uniformity](@): +> if a chunk of text has a certain +> meaning, it will continue to have the same meaning when put into a +> container block (such as a list item or blockquote). + +(Indeed, the spec for [list items] and [block quotes] presupposes +this principle.) This principle implies that if + +``` markdown + * I need to buy + - new shoes + - a coat + - a plane ticket +``` + +is a list item containing a paragraph followed by a nested sublist, +as all Markdown implementations agree it is (though the paragraph +may be rendered without `
` tags, since the list is "tight"), +then + +``` markdown +I need to buy +- new shoes +- a coat +- a plane ticket +``` + +by itself should be a paragraph followed by a nested sublist. + +Since it is well established Markdown practice to allow lists to +interrupt paragraphs inside list items, the [principle of +uniformity] requires us to allow this outside list items as +well. ([reStructuredText](http://docutils.sourceforge.net/rst.html) +takes a different approach, requiring blank lines before lists +even inside other list items.) + +In order to solve of unwanted lists in paragraphs with +hard-wrapped numerals, we allow only lists starting with `1` to +interrupt paragraphs. Thus, + +```````````````````````````````` example +The number of windows in my house is +14. The number of doors is 6. +. +
The number of windows in my house is +14. The number of doors is 6.
+```````````````````````````````` + +We may still get an unintended result in cases like + +```````````````````````````````` example +The number of windows in my house is +1. The number of doors is 6. +. +
The number of windows in my house is
+
+
The number of doors is 6.
+
+```````````````````````````````` + +but this rule should prevent most spurious list captures. + +There can be any number of blank lines between items: + +```````````````````````````````` example +- foo + +- bar + + +- baz +. +
+
+
foo
+
+
+
bar
+
+
+
baz
+
+
+```````````````````````````````` + +```````````````````````````````` example +- foo + - bar + - baz + + + bim +. +
+
foo +
+
bar +
+
+
baz
+
bim
+
+
+
+
+
+
+```````````````````````````````` + + +To separate consecutive lists of the same type, or to separate a +list from an indented code block that would otherwise be parsed +as a subparagraph of the final list item, you can insert a blank HTML +comment: + +```````````````````````````````` example +- foo +- bar + + + +- baz +- bim +. +
+
foo
+
bar
+
+ +
+
baz
+
bim
+
+```````````````````````````````` + + +```````````````````````````````` example +- foo + + notcode + +- foo + + + + code +. +
+
+
foo
+
notcode
+
+
+
foo
+
+
+ +
code +
+```````````````````````````````` + + +List items need not be indented to the same level. The following +list items will be treated as items at the same list level, +since none is indented enough to belong to the previous list +item: + +```````````````````````````````` example +- a + - b + - c + - d + - e + - f +- g +. +
+
a
+
b
+
c
+
d
+
e
+
f
+
g
+
+```````````````````````````````` + + +```````````````````````````````` example +1. a + + 2. b + + 3. c +. +
+
+
a
+
+
+
b
+
+
+
c
+
+
+```````````````````````````````` + +Note, however, that list items may not be preceded by more than +three spaces of indentation. Here `- e` is treated as a paragraph continuation +line, because it is indented more than three spaces: + +```````````````````````````````` example +- a + - b + - c + - d + - e +. +
+
a
+
b
+
c
+
d +- e
+
+```````````````````````````````` + +And here, `3. c` is treated as in indented code block, +because it is indented four spaces and preceded by a +blank line. + +```````````````````````````````` example +1. a + + 2. b + + 3. c +. +
+
+
a
+
+
+
b
+
+
+
3. c +
+```````````````````````````````` + + +This is a loose list, because there is a blank line between +two of the list items: + +```````````````````````````````` example +- a +- b + +- c +. +
+
+
a
+
+
+
b
+
+
+
c
+
+
+```````````````````````````````` + + +So is this, with a empty second item: + +```````````````````````````````` example +* a +* + +* c +. +
+
+
a
+
+
+
+
c
+
+
+```````````````````````````````` + + +These are loose lists, even though there are no blank lines between the items, +because one of the items directly contains two block-level elements +with a blank line between them: + +```````````````````````````````` example +- a +- b + + c +- d +. +
+
+
a
+
+
+
b
+
c
+
+
+
d
+
+
+```````````````````````````````` + + +```````````````````````````````` example +- a +- b + + [ref]: /url +- d +. +
+
+
a
+
+
+
b
+
+
+
d
+
+
+```````````````````````````````` + + +This is a tight list, because the blank lines are in a code block: + +```````````````````````````````` example +- a +- ``` + b + + + ``` +- c +. +
+
a
+
+
b + + +
+
+
c
+
+```````````````````````````````` + + +This is a tight list, because the blank line is between two +paragraphs of a sublist. So the sublist is loose while +the outer list is tight: + +```````````````````````````````` example +- a + - b + + c +- d +. +
+
a +
+
+
b
+
c
+
+
+
+
d
+
+```````````````````````````````` + + +This is a tight list, because the blank line is inside the +block quote: + +```````````````````````````````` example +* a + > b + > +* c +. +
+
a +
+
b
+
+
+
c
+
+```````````````````````````````` + + +This list is tight, because the consecutive block elements +are not separated by blank lines: + +```````````````````````````````` example +- a + > b + ``` + c + ``` +- d +. +
+
a +
+
b
+
+
c +
+
+
d
+
+```````````````````````````````` + + +A single-paragraph list is tight: + +```````````````````````````````` example +- a +. +
+
a
+
+```````````````````````````````` + + +```````````````````````````````` example +- a + - b +. +
+
a +
+
b
+
+
+
+```````````````````````````````` + + +This list is loose, because of the blank line between the +two block elements in the list item: + +```````````````````````````````` example +1. ``` + foo + ``` + + bar +. +
+
+
foo +
+
bar
+
+
+```````````````````````````````` + + +Here the outer list is loose, the inner list tight: + +```````````````````````````````` example +* foo + * bar + + baz +. +
+
+
foo
+
+
bar
+
+
baz
+
+
+```````````````````````````````` + + +```````````````````````````````` example +- a + - b + - c + +- d + - e + - f +. +
+
+
a
+
+
b
+
c
+
+
+
+
d
+
+
e
+
f
+
+
+
+```````````````````````````````` + + +# Inlines + +Inlines are parsed sequentially from the beginning of the character +stream to the end (left to right, in left-to-right languages). +Thus, for example, in + +```````````````````````````````` example +`hi`lo` +. +
hilo`
+```````````````````````````````` + +`hi` is parsed as code, leaving the backtick at the end as a literal +backtick. + + + +## Code spans + +A [backtick string](@) +is a string of one or more backtick characters (`` ` ``) that is neither +preceded nor followed by a backtick. + +A [code span](@) begins with a backtick string and ends with +a backtick string of equal length. The contents of the code span are +the characters between these two backtick strings, normalized in the +following ways: + +- First, [line endings] are converted to [spaces]. +- If the resulting string both begins *and* ends with a [space] + character, but does not consist entirely of [space] + characters, a single [space] character is removed from the + front and back. This allows you to include code that begins + or ends with backtick characters, which must be separated by + whitespace from the opening or closing backtick strings. + +This is a simple code span: + +```````````````````````````````` example +`foo` +. +
foo
+```````````````````````````````` + + +Here two backticks are used, because the code contains a backtick. +This example also illustrates stripping of a single leading and +trailing space: + +```````````````````````````````` example +`` foo ` bar `` +. +
foo ` bar
+```````````````````````````````` + + +This example shows the motivation for stripping leading and trailing +spaces: + +```````````````````````````````` example +` `` ` +. +
``
+```````````````````````````````` + +Note that only *one* space is stripped: + +```````````````````````````````` example +` `` ` +. +
``
+```````````````````````````````` + +The stripping only happens if the space is on both +sides of the string: + +```````````````````````````````` example +` a` +. +
a
+```````````````````````````````` + +Only [spaces], and not [unicode whitespace] in general, are +stripped in this way: + +```````````````````````````````` example +` b ` +. +
b
+```````````````````````````````` + +No stripping occurs if the code span contains only spaces: + +```````````````````````````````` example +` ` +` ` +. +
+
+```````````````````````````````` + + +[Line endings] are treated like spaces: + +```````````````````````````````` example +`` +foo +bar +baz +`` +. +
foo bar baz
+```````````````````````````````` + +```````````````````````````````` example +`` +foo +`` +. +
foo
+```````````````````````````````` + + +Interior spaces are not collapsed: + +```````````````````````````````` example +`foo bar +baz` +. +
foo bar baz
+```````````````````````````````` + +Note that browsers will typically collapse consecutive spaces +when rendering `` elements, so it is recommended that +the following CSS be used: + + code{white-space: pre-wrap;} + + +Note that backslash escapes do not work in code spans. All backslashes +are treated literally: + +```````````````````````````````` example +`foo\`bar` +. +foo\bar` +```````````````````````````````` + + +Backslash escapes are never needed, because one can always choose a +string of *n* backtick characters as delimiters, where the code does +not contain any strings of exactly *n* backtick characters. + +```````````````````````````````` example +``foo`bar`` +. +foo`bar +```````````````````````````````` + +```````````````````````````````` example +` foo `` bar ` +. +foo `` bar +```````````````````````````````` + + +Code span backticks have higher precedence than any other inline +constructs except HTML tags and autolinks. Thus, for example, this is +not parsed as emphasized text, since the second `*` is part of a code +span: + +```````````````````````````````` example +*foo`*` +. +*foo* +```````````````````````````````` + + +And this is not parsed as a link: + +```````````````````````````````` example +[not a `link](/foo`) +. +[not a link](/foo) +```````````````````````````````` + + +Code spans, HTML tags, and autolinks have the same precedence. +Thus, this is code: + +```````````````````````````````` example +`` +. +<a href="">` +```````````````````````````````` + + +But this is an HTML tag: + +```````````````````````````````` example +` +. +` +```````````````````````````````` + + +And this is code: + +```````````````````````````````` example +`` +. +<http://foo.bar.baz>` +```````````````````````````````` + + +But this is an autolink: + +```````````````````````````````` example +` +. +http://foo.bar.`baz` +```````````````````````````````` + + +When a backtick string is not closed by a matching backtick string, +we just have literal backticks: + +```````````````````````````````` example +```foo`` +. +```foo`` +```````````````````````````````` + + +```````````````````````````````` example +`foo +. +`foo +```````````````````````````````` + +The following case also illustrates the need for opening and +closing backtick strings to be equal in length: + +```````````````````````````````` example +`foo``bar`` +. +`foobar +```````````````````````````````` + + +## Emphasis and strong emphasis + +John Gruber's original [Markdown syntax +description](http://daringfireball.net/projects/markdown/syntax#em) says: + +> Markdown treats asterisks (`*`) and underscores (`_`) as indicators of +> emphasis. Text wrapped with one `*` or `_` will be wrapped with an HTML +> `` tag; double `*`'s or `_`'s will be wrapped with an HTML `` +> tag. + +This is enough for most users, but these rules leave much undecided, +especially when it comes to nested emphasis. The original +`Markdown.pl` test suite makes it clear that triple `***` and +`___` delimiters can be used for strong emphasis, and most +implementations have also allowed the following patterns: + +``` markdown +***strong emph*** +***strong** in emph* +***emph* in strong** +**in strong *emph*** +*in emph **strong*** +``` + +The following patterns are less widely supported, but the intent +is clear and they are useful (especially in contexts like bibliography +entries): + +``` markdown +*emph *with emph* in it* +**strong **with strong** in it** +``` + +Many implementations have also restricted intraword emphasis to +the `*` forms, to avoid unwanted emphasis in words containing +internal underscores. (It is best practice to put these in code +spans, but users often do not.) + +``` markdown +internal emphasis: foo*bar*baz +no emphasis: foo_bar_baz +``` + +The rules given below capture all of these patterns, while allowing +for efficient parsing strategies that do not backtrack. + +First, some definitions. A [delimiter run](@) is either +a sequence of one or more `*` characters that is not preceded or +followed by a non-backslash-escaped `*` character, or a sequence +of one or more `_` characters that is not preceded or followed by +a non-backslash-escaped `_` character. + +A [left-flanking delimiter run](@) is +a [delimiter run] that is (1) not followed by [Unicode whitespace], +and either (2a) not followed by a [Unicode punctuation character], or +(2b) followed by a [Unicode punctuation character] and +preceded by [Unicode whitespace] or a [Unicode punctuation character]. +For purposes of this definition, the beginning and the end of +the line count as Unicode whitespace. + +A [right-flanking delimiter run](@) is +a [delimiter run] that is (1) not preceded by [Unicode whitespace], +and either (2a) not preceded by a [Unicode punctuation character], or +(2b) preceded by a [Unicode punctuation character] and +followed by [Unicode whitespace] or a [Unicode punctuation character]. +For purposes of this definition, the beginning and the end of +the line count as Unicode whitespace. + +Here are some examples of delimiter runs. + + - left-flanking but not right-flanking: + + ``` + ***abc + _abc + **"abc" + _"abc" + ``` + + - right-flanking but not left-flanking: + + ``` + abc*** + abc_ + "abc"** + "abc"_ + ``` + + - Both left and right-flanking: + + ``` + abc***def + "abc"_"def" + ``` + + - Neither left nor right-flanking: + + ``` + abc *** def + a _ b + ``` + +(The idea of distinguishing left-flanking and right-flanking +delimiter runs based on the character before and the character +after comes from Roopesh Chander's +[vfmd](http://www.vfmd.org/vfmd-spec/specification/#procedure-for-identifying-emphasis-tags). +vfmd uses the terminology "emphasis indicator string" instead of "delimiter +run," and its rules for distinguishing left- and right-flanking runs +are a bit more complex than the ones given here.) + +The following rules define emphasis and strong emphasis: + +1. A single `*` character [can open emphasis](@) + iff (if and only if) it is part of a [left-flanking delimiter run]. + +2. A single `_` character [can open emphasis] iff + it is part of a [left-flanking delimiter run] + and either (a) not part of a [right-flanking delimiter run] + or (b) part of a [right-flanking delimiter run] + preceded by a [Unicode punctuation character]. + +3. A single `*` character [can close emphasis](@) + iff it is part of a [right-flanking delimiter run]. + +4. A single `_` character [can close emphasis] iff + it is part of a [right-flanking delimiter run] + and either (a) not part of a [left-flanking delimiter run] + or (b) part of a [left-flanking delimiter run] + followed by a [Unicode punctuation character]. + +5. A double `**` [can open strong emphasis](@) + iff it is part of a [left-flanking delimiter run]. + +6. A double `__` [can open strong emphasis] iff + it is part of a [left-flanking delimiter run] + and either (a) not part of a [right-flanking delimiter run] + or (b) part of a [right-flanking delimiter run] + preceded by a [Unicode punctuation character]. + +7. A double `**` [can close strong emphasis](@) + iff it is part of a [right-flanking delimiter run]. + +8. A double `__` [can close strong emphasis] iff + it is part of a [right-flanking delimiter run] + and either (a) not part of a [left-flanking delimiter run] + or (b) part of a [left-flanking delimiter run] + followed by a [Unicode punctuation character]. + +9. Emphasis begins with a delimiter that [can open emphasis] and ends + with a delimiter that [can close emphasis], and that uses the same + character (`_` or `*`) as the opening delimiter. The + opening and closing delimiters must belong to separate + [delimiter runs]. If one of the delimiters can both + open and close emphasis, then the sum of the lengths of the + delimiter runs containing the opening and closing delimiters + must not be a multiple of 3 unless both lengths are + multiples of 3. + +10. Strong emphasis begins with a delimiter that + [can open strong emphasis] and ends with a delimiter that + [can close strong emphasis], and that uses the same character + (`_` or `*`) as the opening delimiter. The + opening and closing delimiters must belong to separate + [delimiter runs]. If one of the delimiters can both open + and close strong emphasis, then the sum of the lengths of + the delimiter runs containing the opening and closing + delimiters must not be a multiple of 3 unless both lengths + are multiples of 3. + +11. A literal `*` character cannot occur at the beginning or end of + `*`-delimited emphasis or `**`-delimited strong emphasis, unless it + is backslash-escaped. + +12. A literal `_` character cannot occur at the beginning or end of + `_`-delimited emphasis or `__`-delimited strong emphasis, unless it + is backslash-escaped. + +Where rules 1--12 above are compatible with multiple parsings, +the following principles resolve ambiguity: + +13. The number of nestings should be minimized. Thus, for example, + an interpretation `...` is always preferred to + `...`. + +14. An interpretation `...` is always + preferred to `...`. + +15. When two potential emphasis or strong emphasis spans overlap, + so that the second begins before the first ends and ends after + the first ends, the first takes precedence. Thus, for example, + `*foo _bar* baz_` is parsed as `foo _bar baz_` rather + than `*foo bar* baz`. + +16. When there are two potential emphasis or strong emphasis spans + with the same closing delimiter, the shorter one (the one that + opens later) takes precedence. Thus, for example, + `**foo **bar baz**` is parsed as `**foo bar baz` + rather than `foo **bar baz`. + +17. Inline code spans, links, images, and HTML tags group more tightly + than emphasis. So, when there is a choice between an interpretation + that contains one of these elements and one that does not, the + former always wins. Thus, for example, `*[foo*](bar)` is + parsed as `*foo*` rather than as + `[foo](bar)`. + +These rules can be illustrated through a series of examples. + +Rule 1: + +```````````````````````````````` example +*foo bar* +. +foo bar +```````````````````````````````` + + +This is not emphasis, because the opening `*` is followed by +whitespace, and hence not part of a [left-flanking delimiter run]: + +```````````````````````````````` example +a * foo bar* +. +a * foo bar* +```````````````````````````````` + + +This is not emphasis, because the opening `*` is preceded +by an alphanumeric and followed by punctuation, and hence +not part of a [left-flanking delimiter run]: + +```````````````````````````````` example +a*"foo"* +. +a*"foo"* +```````````````````````````````` + + +Unicode nonbreaking spaces count as whitespace, too: + +```````````````````````````````` example +* a * +. +* a * +```````````````````````````````` + + +Intraword emphasis with `*` is permitted: + +```````````````````````````````` example +foo*bar* +. +foobar +```````````````````````````````` + + +```````````````````````````````` example +5*6*78 +. +5678 +```````````````````````````````` + + +Rule 2: + +```````````````````````````````` example +_foo bar_ +. +foo bar +```````````````````````````````` + + +This is not emphasis, because the opening `_` is followed by +whitespace: + +```````````````````````````````` example +_ foo bar_ +. +_ foo bar_ +```````````````````````````````` + + +This is not emphasis, because the opening `_` is preceded +by an alphanumeric and followed by punctuation: + +```````````````````````````````` example +a_"foo"_ +. +a_"foo"_ +```````````````````````````````` + + +Emphasis with `_` is not allowed inside words: + +```````````````````````````````` example +foo_bar_ +. +foo_bar_ +```````````````````````````````` + + +```````````````````````````````` example +5_6_78 +. +5_6_78 +```````````````````````````````` + + +```````````````````````````````` example +пристаням_стремятся_ +. +пристаням_стремятся_ +```````````````````````````````` + + +Here `_` does not generate emphasis, because the first delimiter run +is right-flanking and the second left-flanking: + +```````````````````````````````` example +aa_"bb"_cc +. +aa_"bb"_cc +```````````````````````````````` + + +This is emphasis, even though the opening delimiter is +both left- and right-flanking, because it is preceded by +punctuation: + +```````````````````````````````` example +foo-_(bar)_ +. +foo-(bar) +```````````````````````````````` + + +Rule 3: + +This is not emphasis, because the closing delimiter does +not match the opening delimiter: + +```````````````````````````````` example +_foo* +. +_foo* +```````````````````````````````` + + +This is not emphasis, because the closing `*` is preceded by +whitespace: + +```````````````````````````````` example +*foo bar * +. +*foo bar * +```````````````````````````````` + + +A line ending also counts as whitespace: + +```````````````````````````````` example +*foo bar +* +. +*foo bar +* +```````````````````````````````` + + +This is not emphasis, because the second `*` is +preceded by punctuation and followed by an alphanumeric +(hence it is not part of a [right-flanking delimiter run]: + +```````````````````````````````` example +*(*foo) +. +*(*foo) +```````````````````````````````` + + +The point of this restriction is more easily appreciated +with this example: + +```````````````````````````````` example +*(*foo*)* +. +(foo) +```````````````````````````````` + + +Intraword emphasis with `*` is allowed: + +```````````````````````````````` example +*foo*bar +. +foobar +```````````````````````````````` + + + +Rule 4: + +This is not emphasis, because the closing `_` is preceded by +whitespace: + +```````````````````````````````` example +_foo bar _ +. +_foo bar _ +```````````````````````````````` + + +This is not emphasis, because the second `_` is +preceded by punctuation and followed by an alphanumeric: + +```````````````````````````````` example +_(_foo) +. +_(_foo) +```````````````````````````````` + + +This is emphasis within emphasis: + +```````````````````````````````` example +_(_foo_)_ +. +(foo) +```````````````````````````````` + + +Intraword emphasis is disallowed for `_`: + +```````````````````````````````` example +_foo_bar +. +_foo_bar +```````````````````````````````` + + +```````````````````````````````` example +_пристаням_стремятся +. +_пристаням_стремятся +```````````````````````````````` + + +```````````````````````````````` example +_foo_bar_baz_ +. +foo_bar_baz +```````````````````````````````` + + +This is emphasis, even though the closing delimiter is +both left- and right-flanking, because it is followed by +punctuation: + +```````````````````````````````` example +_(bar)_. +. +(bar). +```````````````````````````````` + + +Rule 5: + +```````````````````````````````` example +**foo bar** +. +foo bar +```````````````````````````````` + + +This is not strong emphasis, because the opening delimiter is +followed by whitespace: + +```````````````````````````````` example +** foo bar** +. +** foo bar** +```````````````````````````````` + + +This is not strong emphasis, because the opening `**` is preceded +by an alphanumeric and followed by punctuation, and hence +not part of a [left-flanking delimiter run]: + +```````````````````````````````` example +a**"foo"** +. +a**"foo"** +```````````````````````````````` + + +Intraword strong emphasis with `**` is permitted: + +```````````````````````````````` example +foo**bar** +. +foobar +```````````````````````````````` + + +Rule 6: + +```````````````````````````````` example +__foo bar__ +. +foo bar +```````````````````````````````` + + +This is not strong emphasis, because the opening delimiter is +followed by whitespace: + +```````````````````````````````` example +__ foo bar__ +. +__ foo bar__ +```````````````````````````````` + + +A line ending counts as whitespace: +```````````````````````````````` example +__ +foo bar__ +. +__ +foo bar__ +```````````````````````````````` + + +This is not strong emphasis, because the opening `__` is preceded +by an alphanumeric and followed by punctuation: + +```````````````````````````````` example +a__"foo"__ +. +a__"foo"__ +```````````````````````````````` + + +Intraword strong emphasis is forbidden with `__`: + +```````````````````````````````` example +foo__bar__ +. +foo__bar__ +```````````````````````````````` + + +```````````````````````````````` example +5__6__78 +. +5__6__78 +```````````````````````````````` + + +```````````````````````````````` example +пристаням__стремятся__ +. +пристаням__стремятся__ +```````````````````````````````` + + +```````````````````````````````` example +__foo, __bar__, baz__ +. +foo, bar, baz +```````````````````````````````` + + +This is strong emphasis, even though the opening delimiter is +both left- and right-flanking, because it is preceded by +punctuation: + +```````````````````````````````` example +foo-__(bar)__ +. +foo-(bar) +```````````````````````````````` + + + +Rule 7: + +This is not strong emphasis, because the closing delimiter is preceded +by whitespace: + +```````````````````````````````` example +**foo bar ** +. +**foo bar ** +```````````````````````````````` + + +(Nor can it be interpreted as an emphasized `*foo bar *`, because of +Rule 11.) + +This is not strong emphasis, because the second `**` is +preceded by punctuation and followed by an alphanumeric: + +```````````````````````````````` example +**(**foo) +. +**(**foo) +```````````````````````````````` + + +The point of this restriction is more easily appreciated +with these examples: + +```````````````````````````````` example +*(**foo**)* +. +(foo) +```````````````````````````````` + + +```````````````````````````````` example +**Gomphocarpus (*Gomphocarpus physocarpus*, syn. +*Asclepias physocarpa*)** +. +Gomphocarpus (Gomphocarpus physocarpus, syn. +Asclepias physocarpa) +```````````````````````````````` + + +```````````````````````````````` example +**foo "*bar*" foo** +. +foo "bar" foo +```````````````````````````````` + + +Intraword emphasis: + +```````````````````````````````` example +**foo**bar +. +foobar +```````````````````````````````` + + +Rule 8: + +This is not strong emphasis, because the closing delimiter is +preceded by whitespace: + +```````````````````````````````` example +__foo bar __ +. +__foo bar __ +```````````````````````````````` + + +This is not strong emphasis, because the second `__` is +preceded by punctuation and followed by an alphanumeric: + +```````````````````````````````` example +__(__foo) +. +__(__foo) +```````````````````````````````` + + +The point of this restriction is more easily appreciated +with this example: + +```````````````````````````````` example +_(__foo__)_ +. +(foo) +```````````````````````````````` + + +Intraword strong emphasis is forbidden with `__`: + +```````````````````````````````` example +__foo__bar +. +__foo__bar +```````````````````````````````` + + +```````````````````````````````` example +__пристаням__стремятся +. +__пристаням__стремятся +```````````````````````````````` + + +```````````````````````````````` example +__foo__bar__baz__ +. +foo__bar__baz +```````````````````````````````` + + +This is strong emphasis, even though the closing delimiter is +both left- and right-flanking, because it is followed by +punctuation: + +```````````````````````````````` example +__(bar)__. +. +(bar). +```````````````````````````````` + + +Rule 9: + +Any nonempty sequence of inline elements can be the contents of an +emphasized span. + +```````````````````````````````` example +*foo [bar](/url)* +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +*foo +bar* +. +foo +bar +```````````````````````````````` + + +In particular, emphasis and strong emphasis can be nested +inside emphasis: + +```````````````````````````````` example +_foo __bar__ baz_ +. +foo bar baz +```````````````````````````````` + + +```````````````````````````````` example +_foo _bar_ baz_ +. +foo bar baz +```````````````````````````````` + + +```````````````````````````````` example +__foo_ bar_ +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +*foo *bar** +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +*foo **bar** baz* +. +foo bar baz +```````````````````````````````` + +```````````````````````````````` example +*foo**bar**baz* +. +foobarbaz +```````````````````````````````` + +Note that in the preceding case, the interpretation + +``` markdown +foobarbaz +``` + + +is precluded by the condition that a delimiter that +can both open and close (like the `*` after `foo`) +cannot form emphasis if the sum of the lengths of +the delimiter runs containing the opening and +closing delimiters is a multiple of 3 unless +both lengths are multiples of 3. + + +For the same reason, we don't get two consecutive +emphasis sections in this example: + +```````````````````````````````` example +*foo**bar* +. +foo**bar +```````````````````````````````` + + +The same condition ensures that the following +cases are all strong emphasis nested inside +emphasis, even when the interior whitespace is +omitted: + + +```````````````````````````````` example +***foo** bar* +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +*foo **bar*** +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +*foo**bar*** +. +foobar +```````````````````````````````` + + +When the lengths of the interior closing and opening +delimiter runs are *both* multiples of 3, though, +they can match to create emphasis: + +```````````````````````````````` example +foo***bar***baz +. +foobarbaz +```````````````````````````````` + +```````````````````````````````` example +foo******bar*********baz +. +foobar***baz +```````````````````````````````` + + +Indefinite levels of nesting are possible: + +```````````````````````````````` example +*foo **bar *baz* bim** bop* +. +foo bar baz bim bop +```````````````````````````````` + + +```````````````````````````````` example +*foo [*bar*](/url)* +. +foo bar +```````````````````````````````` + + +There can be no empty emphasis or strong emphasis: + +```````````````````````````````` example +** is not an empty emphasis +. +** is not an empty emphasis +```````````````````````````````` + + +```````````````````````````````` example +**** is not an empty strong emphasis +. +**** is not an empty strong emphasis +```````````````````````````````` + + + +Rule 10: + +Any nonempty sequence of inline elements can be the contents of an +strongly emphasized span. + +```````````````````````````````` example +**foo [bar](/url)** +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +**foo +bar** +. +foo +bar +```````````````````````````````` + + +In particular, emphasis and strong emphasis can be nested +inside strong emphasis: + +```````````````````````````````` example +__foo _bar_ baz__ +. +foo bar baz +```````````````````````````````` + + +```````````````````````````````` example +__foo __bar__ baz__ +. +foo bar baz +```````````````````````````````` + + +```````````````````````````````` example +____foo__ bar__ +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +**foo **bar**** +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +**foo *bar* baz** +. +foo bar baz +```````````````````````````````` + + +```````````````````````````````` example +**foo*bar*baz** +. +foobarbaz +```````````````````````````````` + + +```````````````````````````````` example +***foo* bar** +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +**foo *bar*** +. +foo bar +```````````````````````````````` + + +Indefinite levels of nesting are possible: + +```````````````````````````````` example +**foo *bar **baz** +bim* bop** +. +foo bar baz +bim bop +```````````````````````````````` + + +```````````````````````````````` example +**foo [*bar*](/url)** +. +foo bar +```````````````````````````````` + + +There can be no empty emphasis or strong emphasis: + +```````````````````````````````` example +__ is not an empty emphasis +. +__ is not an empty emphasis +```````````````````````````````` + + +```````````````````````````````` example +____ is not an empty strong emphasis +. +____ is not an empty strong emphasis +```````````````````````````````` + + + +Rule 11: + +```````````````````````````````` example +foo *** +. +foo *** +```````````````````````````````` + + +```````````````````````````````` example +foo *\** +. +foo * +```````````````````````````````` + + +```````````````````````````````` example +foo *_* +. +foo _ +```````````````````````````````` + + +```````````````````````````````` example +foo ***** +. +foo ***** +```````````````````````````````` + + +```````````````````````````````` example +foo **\*** +. +foo * +```````````````````````````````` + + +```````````````````````````````` example +foo **_** +. +foo _ +```````````````````````````````` + + +Note that when delimiters do not match evenly, Rule 11 determines +that the excess literal `*` characters will appear outside of the +emphasis, rather than inside it: + +```````````````````````````````` example +**foo* +. +*foo +```````````````````````````````` + + +```````````````````````````````` example +*foo** +. +foo* +```````````````````````````````` + + +```````````````````````````````` example +***foo** +. +*foo +```````````````````````````````` + + +```````````````````````````````` example +****foo* +. +***foo +```````````````````````````````` + + +```````````````````````````````` example +**foo*** +. +foo* +```````````````````````````````` + + +```````````````````````````````` example +*foo**** +. +foo*** +```````````````````````````````` + + + +Rule 12: + +```````````````````````````````` example +foo ___ +. +foo ___ +```````````````````````````````` + + +```````````````````````````````` example +foo _\__ +. +foo _ +```````````````````````````````` + + +```````````````````````````````` example +foo _*_ +. +foo * +```````````````````````````````` + + +```````````````````````````````` example +foo _____ +. +foo _____ +```````````````````````````````` + + +```````````````````````````````` example +foo __\___ +. +foo _ +```````````````````````````````` + + +```````````````````````````````` example +foo __*__ +. +foo * +```````````````````````````````` + + +```````````````````````````````` example +__foo_ +. +_foo +```````````````````````````````` + + +Note that when delimiters do not match evenly, Rule 12 determines +that the excess literal `_` characters will appear outside of the +emphasis, rather than inside it: + +```````````````````````````````` example +_foo__ +. +foo_ +```````````````````````````````` + + +```````````````````````````````` example +___foo__ +. +_foo +```````````````````````````````` + + +```````````````````````````````` example +____foo_ +. +___foo +```````````````````````````````` + + +```````````````````````````````` example +__foo___ +. +foo_ +```````````````````````````````` + + +```````````````````````````````` example +_foo____ +. +foo___ +```````````````````````````````` + + +Rule 13 implies that if you want emphasis nested directly inside +emphasis, you must use different delimiters: + +```````````````````````````````` example +**foo** +. +foo +```````````````````````````````` + + +```````````````````````````````` example +*_foo_* +. +foo +```````````````````````````````` + + +```````````````````````````````` example +__foo__ +. +foo +```````````````````````````````` + + +```````````````````````````````` example +_*foo*_ +. +foo +```````````````````````````````` + + +However, strong emphasis within strong emphasis is possible without +switching delimiters: + +```````````````````````````````` example +****foo**** +. +foo +```````````````````````````````` + + +```````````````````````````````` example +____foo____ +. +foo +```````````````````````````````` + + + +Rule 13 can be applied to arbitrarily long sequences of +delimiters: + +```````````````````````````````` example +******foo****** +. +foo +```````````````````````````````` + + +Rule 14: + +```````````````````````````````` example +***foo*** +. +foo +```````````````````````````````` + + +```````````````````````````````` example +_____foo_____ +. +foo +```````````````````````````````` + + +Rule 15: + +```````````````````````````````` example +*foo _bar* baz_ +. +foo _bar baz_ +```````````````````````````````` + + +```````````````````````````````` example +*foo __bar *baz bim__ bam* +. +foo bar *baz bim bam +```````````````````````````````` + + +Rule 16: + +```````````````````````````````` example +**foo **bar baz** +. +**foo bar baz +```````````````````````````````` + + +```````````````````````````````` example +*foo *bar baz* +. +*foo bar baz +```````````````````````````````` + + +Rule 17: + +```````````````````````````````` example +*[bar*](/url) +. +*bar* +```````````````````````````````` + + +```````````````````````````````` example +_foo [bar_](/url) +. +_foo bar_ +```````````````````````````````` + + +```````````````````````````````` example +* +. +* +```````````````````````````````` + + +```````````````````````````````` example +** +. +** +```````````````````````````````` + + +```````````````````````````````` example +__ +. +__ +```````````````````````````````` + + +```````````````````````````````` example +*a `*`* +. +a * +```````````````````````````````` + + +```````````````````````````````` example +_a `_`_ +. +a _ +```````````````````````````````` + + +```````````````````````````````` example +**a +. +**ahttp://foo.bar/?q=** +```````````````````````````````` + + +```````````````````````````````` example +__a +. +__ahttp://foo.bar/?q=__ +```````````````````````````````` + + + +## Links + +A link contains [link text] (the visible text), a [link destination] +(the URI that is the link destination), and optionally a [link title]. +There are two basic kinds of links in Markdown. In [inline links] the +destination and title are given immediately after the link text. In +[reference links] the destination and title are defined elsewhere in +the document. + +A [link text](@) consists of a sequence of zero or more +inline elements enclosed by square brackets (`[` and `]`). The +following rules apply: + +- Links may not contain other links, at any level of nesting. If + multiple otherwise valid link definitions appear nested inside each + other, the inner-most definition is used. + +- Brackets are allowed in the [link text] only if (a) they + are backslash-escaped or (b) they appear as a matched pair of brackets, + with an open bracket `[`, a sequence of zero or more inlines, and + a close bracket `]`. + +- Backtick [code spans], [autolinks], and raw [HTML tags] bind more tightly + than the brackets in link text. Thus, for example, + `` [foo`]` `` could not be a link text, since the second `]` + is part of a code span. + +- The brackets in link text bind more tightly than markers for + [emphasis and strong emphasis]. Thus, for example, `*[foo*](url)` is a link. + +A [link destination](@) consists of either + +- a sequence of zero or more characters between an opening `<` and a + closing `>` that contains no line endings or unescaped + `<` or `>` characters, or + +- a nonempty sequence of characters that does not start with `<`, + does not include [ASCII control characters][ASCII control character] + or [space] character, and includes parentheses only if (a) they are + backslash-escaped or (b) they are part of a balanced pair of + unescaped parentheses. + (Implementations may impose limits on parentheses nesting to + avoid performance issues, but at least three levels of nesting + should be supported.) + +A [link title](@) consists of either + +- a sequence of zero or more characters between straight double-quote + characters (`"`), including a `"` character only if it is + backslash-escaped, or + +- a sequence of zero or more characters between straight single-quote + characters (`'`), including a `'` character only if it is + backslash-escaped, or + +- a sequence of zero or more characters between matching parentheses + (`(...)`), including a `(` or `)` character only if it is + backslash-escaped. + +Although [link titles] may span multiple lines, they may not contain +a [blank line]. + +An [inline link](@) consists of a [link text] followed immediately +by a left parenthesis `(`, an optional [link destination], an optional +[link title], and a right parenthesis `)`. +These four components may be separated by spaces, tabs, and up to one line +ending. +If both [link destination] and [link title] are present, they *must* be +separated by spaces, tabs, and up to one line ending. + +The link's text consists of the inlines contained +in the [link text] (excluding the enclosing square brackets). +The link's URI consists of the link destination, excluding enclosing +`<...>` if present, with backslash-escapes in effect as described +above. The link's title consists of the link title, excluding its +enclosing delimiters, with backslash-escapes in effect as described +above. + +Here is a simple inline link: + +```````````````````````````````` example +[link](/uri "title") +. +link +```````````````````````````````` + + +The title, the link text and even +the destination may be omitted: + +```````````````````````````````` example +[link](/uri) +. +link +```````````````````````````````` + +```````````````````````````````` example +[](./target.md) +. + +```````````````````````````````` + + +```````````````````````````````` example +[link]() +. +link +```````````````````````````````` + + +```````````````````````````````` example +[link](<>) +. +link +```````````````````````````````` + + +```````````````````````````````` example +[]() +. + +```````````````````````````````` + +The destination can only contain spaces if it is +enclosed in pointy brackets: + +```````````````````````````````` example +[link](/my uri) +. +[link](/my uri) +```````````````````````````````` + +```````````````````````````````` example +[link]() +. +link +```````````````````````````````` + +The destination cannot contain line endings, +even if enclosed in pointy brackets: + +```````````````````````````````` example +[link](foo +bar) +. +[link](foo +bar) +```````````````````````````````` + +```````````````````````````````` example +[link]() +. +[link]() +```````````````````````````````` + +The destination can contain `)` if it is enclosed +in pointy brackets: + +```````````````````````````````` example +[a]() +. +a +```````````````````````````````` + +Pointy brackets that enclose links must be unescaped: + +```````````````````````````````` example +[link]() +. +[link](<foo>) +```````````````````````````````` + +These are not links, because the opening pointy bracket +is not matched properly: + +```````````````````````````````` example +[a]( +[a](c) +. +[a](<b)c +[a](<b)c> +[a](c) +```````````````````````````````` + +Parentheses inside the link destination may be escaped: + +```````````````````````````````` example +[link]($foo$) +. +link +```````````````````````````````` + +Any number of parentheses are allowed without escaping, as long as they are +balanced: + +```````````````````````````````` example +[link](foo(and(bar))) +. +link +```````````````````````````````` + +However, if you have unbalanced parentheses, you need to escape or use the +`<...>` form: + +```````````````````````````````` example +[link](foo(and(bar)) +. +[link](foo(and(bar)) +```````````````````````````````` + + +```````````````````````````````` example +[link](foo$and\(bar$) +. +link +```````````````````````````````` + + +```````````````````````````````` example +[link]() +. +link +```````````````````````````````` + + +Parentheses and other symbols can also be escaped, as usual +in Markdown: + +```````````````````````````````` example +[link](foo\)\:) +. +link +```````````````````````````````` + + +A link can contain fragment identifiers and queries: + +```````````````````````````````` example +[link](#fragment) + +[link](http://example.com#fragment) + +[link](http://example.com?foo=3#frag) +. +link +link +link +```````````````````````````````` + + +Note that a backslash before a non-escapable character is +just a backslash: + +```````````````````````````````` example +[link](foo\bar) +. +link +```````````````````````````````` + + +URL-escaping should be left alone inside the destination, as all +URL-escaped characters are also valid URL characters. Entity and +numerical character references in the destination will be parsed +into the corresponding Unicode code points, as usual. These may +be optionally URL-escaped when written as HTML, but this spec +does not enforce any particular policy for rendering URLs in +HTML or other formats. Renderers may make different decisions +about how to escape or normalize URLs in the output. + +```````````````````````````````` example +[link](foo%20bä) +. +link +```````````````````````````````` + + +Note that, because titles can often be parsed as destinations, +if you try to omit the destination and keep the title, you'll +get unexpected results: + +```````````````````````````````` example +[link]("title") +. +link +```````````````````````````````` + + +Titles may be in single quotes, double quotes, or parentheses: + +```````````````````````````````` example +[link](/url "title") +[link](/url 'title') +[link](/url (title)) +. +link +link +link +```````````````````````````````` + + +Backslash escapes and entity and numeric character references +may be used in titles: + +```````````````````````````````` example +[link](/url "title \""") +. +link +```````````````````````````````` + + +Titles must be separated from the link using spaces, tabs, and up to one line +ending. +Other [Unicode whitespace] like non-breaking space doesn't work. + +```````````````````````````````` example +[link](/url "title") +. +link +```````````````````````````````` + + +Nested balanced quotes are not allowed without escaping: + +```````````````````````````````` example +[link](/url "title "and" title") +. +[link](/url "title "and" title") +```````````````````````````````` + + +But it is easy to work around this by using a different quote type: + +```````````````````````````````` example +[link](/url 'title "and" title') +. +link +```````````````````````````````` + + +(Note: `Markdown.pl` did allow double quotes inside a double-quoted +title, and its test suite included a test demonstrating this. +But it is hard to see a good rationale for the extra complexity this +brings, since there are already many ways---backslash escaping, +entity and numeric character references, or using a different +quote type for the enclosing title---to write titles containing +double quotes. `Markdown.pl`'s handling of titles has a number +of other strange features. For example, it allows single-quoted +titles in inline links, but not reference links. And, in +reference links but not inline links, it allows a title to begin +with `"` and end with `)`. `Markdown.pl` 1.0.1 even allows +titles with no closing quotation mark, though 1.0.2b8 does not. +It seems preferable to adopt a simple, rational rule that works +the same way in inline links and link reference definitions.) + +Spaces, tabs, and up to one line ending is allowed around the destination and +title: + +```````````````````````````````` example +[link]( /uri + "title" ) +. +link +```````````````````````````````` + + +But it is not allowed between the link text and the +following parenthesis: + +```````````````````````````````` example +[link] (/uri) +. +[link] (/uri) +```````````````````````````````` + + +The link text may contain balanced brackets, but not unbalanced ones, +unless they are escaped: + +```````````````````````````````` example +[link [foo [bar]]](/uri) +. +link [foo [bar]] +```````````````````````````````` + + +```````````````````````````````` example +[link] bar](/uri) +. +[link] bar](/uri) +```````````````````````````````` + + +```````````````````````````````` example +[link [bar](/uri) +. +[link bar +```````````````````````````````` + + +```````````````````````````````` example +[link \[bar](/uri) +. +link [bar +```````````````````````````````` + + +The link text may contain inline content: + +```````````````````````````````` example +[link *foo **bar** `#`*](/uri) +. +link foo bar # +```````````````````````````````` + + +```````````````````````````````` example +[![moon](moon.jpg)](/uri) +. + +```````````````````````````````` + + +However, links may not contain other links, at any level of nesting. + +```````````````````````````````` example +[foo [bar](/uri)](/uri) +. +[foo bar](/uri) +```````````````````````````````` + + +```````````````````````````````` example +[foo *[bar [baz](/uri)](/uri)*](/uri) +. +[foo [bar baz](/uri)](/uri) +```````````````````````````````` + + +```````````````````````````````` example +![[[foo](uri1)](uri2)](uri3) +. + +```````````````````````````````` + + +These cases illustrate the precedence of link text grouping over +emphasis grouping: + +```````````````````````````````` example +*[foo*](/uri) +. +*foo* +```````````````````````````````` + + +```````````````````````````````` example +[foo *bar](baz*) +. +foo *bar +```````````````````````````````` + + +Note that brackets that *aren't* part of links do not take +precedence: + +```````````````````````````````` example +*foo [bar* baz] +. +foo [bar baz] +```````````````````````````````` + + +These cases illustrate the precedence of HTML tags, code spans, +and autolinks over link grouping: + +```````````````````````````````` example +[foo +. +[foo +```````````````````````````````` + + +```````````````````````````````` example +[foo`](/uri)` +. +[foo](/uri) +```````````````````````````````` + + +```````````````````````````````` example +[foo +. +[foohttp://example.com/?search=](uri) +```````````````````````````````` + + +There are three kinds of [reference link](@)s: +[full](#full-reference-link), [collapsed](#collapsed-reference-link), +and [shortcut](#shortcut-reference-link). + +A [full reference link](@) +consists of a [link text] immediately followed by a [link label] +that [matches] a [link reference definition] elsewhere in the document. + +A [link label](@) begins with a left bracket (`[`) and ends +with the first right bracket (`]`) that is not backslash-escaped. +Between these brackets there must be at least one character that is not a space, +tab, or line ending. +Unescaped square bracket characters are not allowed inside the +opening and closing square brackets of [link labels]. A link +label can have at most 999 characters inside the square +brackets. + +One label [matches](@) +another just in case their normalized forms are equal. To normalize a +label, strip off the opening and closing brackets, +perform the *Unicode case fold*, strip leading and trailing +spaces, tabs, and line endings, and collapse consecutive internal +spaces, tabs, and line endings to a single space. If there are multiple +matching reference link definitions, the one that comes first in the +document is used. (It is desirable in such cases to emit a warning.) + +The link's URI and title are provided by the matching [link +reference definition]. + +Here is a simple example: + +```````````````````````````````` example +[foo][bar] + +[bar]: /url "title" +. +foo +```````````````````````````````` + + +The rules for the [link text] are the same as with +[inline links]. Thus: + +The link text may contain balanced brackets, but not unbalanced ones, +unless they are escaped: + +```````````````````````````````` example +[link [foo [bar]]][ref] + +[ref]: /uri +. +link [foo [bar]] +```````````````````````````````` + + +```````````````````````````````` example +[link \[bar][ref] + +[ref]: /uri +. +link [bar +```````````````````````````````` + + +The link text may contain inline content: + +```````````````````````````````` example +[link *foo **bar** `#`*][ref] + +[ref]: /uri +. +link foo bar # +```````````````````````````````` + + +```````````````````````````````` example +[![moon](moon.jpg)][ref] + +[ref]: /uri +. + +```````````````````````````````` + + +However, links may not contain other links, at any level of nesting. + +```````````````````````````````` example +[foo [bar](/uri)][ref] + +[ref]: /uri +. +[foo bar]ref +```````````````````````````````` + + +```````````````````````````````` example +[foo *bar [baz][ref]*][ref] + +[ref]: /uri +. +[foo bar baz]ref +```````````````````````````````` + + +(In the examples above, we have two [shortcut reference links] +instead of one [full reference link].) + +The following cases illustrate the precedence of link text grouping over +emphasis grouping: + +```````````````````````````````` example +*[foo*][ref] + +[ref]: /uri +. +*foo* +```````````````````````````````` + + +```````````````````````````````` example +[foo *bar][ref]* + +[ref]: /uri +. +foo *bar* +```````````````````````````````` + + +These cases illustrate the precedence of HTML tags, code spans, +and autolinks over link grouping: + +```````````````````````````````` example +[foo + +[ref]: /uri +. +[foo +```````````````````````````````` + + +```````````````````````````````` example +[foo`][ref]` + +[ref]: /uri +. +[foo][ref] +```````````````````````````````` + + +```````````````````````````````` example +[foo + +[ref]: /uri +. +[foohttp://example.com/?search=][ref] +```````````````````````````````` + + +Matching is case-insensitive: + +```````````````````````````````` example +[foo][BaR] + +[bar]: /url "title" +. +foo +```````````````````````````````` + + +Unicode case fold is used: + +```````````````````````````````` example +[ẞ] + +[SS]: /url +. +ẞ +```````````````````````````````` + + +Consecutive internal spaces, tabs, and line endings are treated as one space for +purposes of determining matching: + +```````````````````````````````` example +[Foo + bar]: /url + +[Baz][Foo bar] +. +Baz +```````````````````````````````` + + +No spaces, tabs, or line endings are allowed between the [link text] and the +[link label]: + +```````````````````````````````` example +[foo] [bar] + +[bar]: /url "title" +. +[foo] bar +```````````````````````````````` + + +```````````````````````````````` example +[foo] +[bar] + +[bar]: /url "title" +. +[foo] +bar +```````````````````````````````` + + +This is a departure from John Gruber's original Markdown syntax +description, which explicitly allows whitespace between the link +text and the link label. It brings reference links in line with +[inline links], which (according to both original Markdown and +this spec) cannot have whitespace after the link text. More +importantly, it prevents inadvertent capture of consecutive +[shortcut reference links]. If whitespace is allowed between the +link text and the link label, then in the following we will have +a single reference link, not two shortcut reference links, as +intended: + +``` markdown +[foo] +[bar] + +[foo]: /url1 +[bar]: /url2 +``` + +(Note that [shortcut reference links] were introduced by Gruber +himself in a beta version of `Markdown.pl`, but never included +in the official syntax description. Without shortcut reference +links, it is harmless to allow space between the link text and +link label; but once shortcut references are introduced, it is +too dangerous to allow this, as it frequently leads to +unintended results.) + +When there are multiple matching [link reference definitions], +the first is used: + +```````````````````````````````` example +[foo]: /url1 + +[foo]: /url2 + +[bar][foo] +. +bar +```````````````````````````````` + + +Note that matching is performed on normalized strings, not parsed +inline content. So the following does not match, even though the +labels define equivalent inline content: + +```````````````````````````````` example +[bar][foo\!] + +[foo!]: /url +. +[bar][foo!] +```````````````````````````````` + + +[Link labels] cannot contain brackets, unless they are +backslash-escaped: + +```````````````````````````````` example +[foo][ref[] + +[ref[]: /uri +. +[foo][ref[] +[ref[]: /uri +```````````````````````````````` + + +```````````````````````````````` example +[foo][ref[bar]] + +[ref[bar]]: /uri +. +[foo][ref[bar]] +[ref[bar]]: /uri +```````````````````````````````` + + +```````````````````````````````` example +[[[foo]]] + +[[[foo]]]: /url +. +[[[foo]]] +[[[foo]]]: /url +```````````````````````````````` + + +```````````````````````````````` example +[foo][ref\[] + +[ref\[]: /uri +. +foo +```````````````````````````````` + + +Note that in this example `]` is not backslash-escaped: + +```````````````````````````````` example +[bar\\]: /uri + +[bar\\] +. +bar\ +```````````````````````````````` + + +A [link label] must contain at least one character that is not a space, tab, or +line ending: + +```````````````````````````````` example +[] + +[]: /uri +. +[] +[]: /uri +```````````````````````````````` + + +```````````````````````````````` example +[ + ] + +[ + ]: /uri +. +[ +] +[ +]: /uri +```````````````````````````````` + + +A [collapsed reference link](@) +consists of a [link label] that [matches] a +[link reference definition] elsewhere in the +document, followed by the string `[]`. +The contents of the first link label are parsed as inlines, +which are used as the link's text. The link's URI and title are +provided by the matching reference link definition. Thus, +`[foo][]` is equivalent to `[foo][foo]`. + +```````````````````````````````` example +[foo][] + +[foo]: /url "title" +. +foo +```````````````````````````````` + + +```````````````````````````````` example +[*foo* bar][] + +[*foo* bar]: /url "title" +. +foo bar +```````````````````````````````` + + +The link labels are case-insensitive: + +```````````````````````````````` example +[Foo][] + +[foo]: /url "title" +. +Foo +```````````````````````````````` + + + +As with full reference links, spaces, tabs, or line endings are not +allowed between the two sets of brackets: + +```````````````````````````````` example +[foo] +[] + +[foo]: /url "title" +. +foo +[] +```````````````````````````````` + + +A [shortcut reference link](@) +consists of a [link label] that [matches] a +[link reference definition] elsewhere in the +document and is not followed by `[]` or a link label. +The contents of the first link label are parsed as inlines, +which are used as the link's text. The link's URI and title +are provided by the matching link reference definition. +Thus, `[foo]` is equivalent to `[foo][]`. + +```````````````````````````````` example +[foo] + +[foo]: /url "title" +. +foo +```````````````````````````````` + + +```````````````````````````````` example +[*foo* bar] + +[*foo* bar]: /url "title" +. +foo bar +```````````````````````````````` + + +```````````````````````````````` example +[[*foo* bar]] + +[*foo* bar]: /url "title" +. +[foo bar] +```````````````````````````````` + + +```````````````````````````````` example +[[bar [foo] + +[foo]: /url +. +[[bar foo +```````````````````````````````` + + +The link labels are case-insensitive: + +```````````````````````````````` example +[Foo] + +[foo]: /url "title" +. +Foo +```````````````````````````````` + + +A space after the link text should be preserved: + +```````````````````````````````` example +[foo] bar + +[foo]: /url +. +foo bar +```````````````````````````````` + + +If you just want bracketed text, you can backslash-escape the +opening bracket to avoid links: + +```````````````````````````````` example +\[foo] + +[foo]: /url "title" +. +[foo] +```````````````````````````````` + + +Note that this is a link, because a link label ends with the first +following closing bracket: + +```````````````````````````````` example +[foo*]: /url + +*[foo*] +. +*foo* +```````````````````````````````` + + +Full and compact references take precedence over shortcut +references: + +```````````````````````````````` example +[foo][bar] + +[foo]: /url1 +[bar]: /url2 +. +foo +```````````````````````````````` + +```````````````````````````````` example +[foo][] + +[foo]: /url1 +. +foo +```````````````````````````````` + +Inline links also take precedence: + +```````````````````````````````` example +[foo]() + +[foo]: /url1 +. +foo +```````````````````````````````` + +```````````````````````````````` example +[foo](not a link) + +[foo]: /url1 +. +foo(not a link) +```````````````````````````````` + +In the following case `[bar][baz]` is parsed as a reference, +`[foo]` as normal text: + +```````````````````````````````` example +[foo][bar][baz] + +[baz]: /url +. +[foo]bar +```````````````````````````````` + + +Here, though, `[foo][bar]` is parsed as a reference, since +`[bar]` is defined: + +```````````````````````````````` example +[foo][bar][baz] + +[baz]: /url1 +[bar]: /url2 +. +foobaz +```````````````````````````````` + + +Here `[foo]` is not parsed as a shortcut reference, because it +is followed by a link label (even though `[bar]` is not defined): + +```````````````````````````````` example +[foo][bar][baz] + +[baz]: /url1 +[foo]: /url2 +. +[foo]bar +```````````````````````````````` + + + +## Images + +Syntax for images is like the syntax for links, with one +difference. Instead of [link text], we have an +[image description](@). The rules for this are the +same as for [link text], except that (a) an +image description starts with `![` rather than `[`, and +(b) an image description may contain links. +An image description has inline elements +as its contents. When an image is rendered to HTML, +this is standardly used as the image's `alt` attribute. + +```````````````````````````````` example +![foo](/url "title") +. + +```````````````````````````````` + + +```````````````````````````````` example +![foo *bar*] + +[foo *bar*]: train.jpg "train & tracks" +. + +```````````````````````````````` + + +```````````````````````````````` example +![foo ![bar](/url)](/url2) +. + +```````````````````````````````` + + +```````````````````````````````` example +![foo [bar](/url)](/url2) +. + +```````````````````````````````` + + +Though this spec is concerned with parsing, not rendering, it is +recommended that in rendering to HTML, only the plain string content +of the [image description] be used. Note that in +the above example, the alt attribute's value is `foo bar`, not `foo +[bar](/url)` or `foo bar`. Only the plain string +content is rendered, without formatting. + +```````````````````````````````` example +![foo *bar*][] + +[foo *bar*]: train.jpg "train & tracks" +. + +```````````````````````````````` + + +```````````````````````````````` example +![foo *bar*][foobar] + +[FOOBAR]: train.jpg "train & tracks" +. + +```````````````````````````````` + + +```````````````````````````````` example +![foo](train.jpg) +. + +```````````````````````````````` + + +```````````````````````````````` example +My ![foo bar](/path/to/train.jpg "title" ) +. +My +```````````````````````````````` + + +```````````````````````````````` example +![foo]() +. + +```````````````````````````````` + + +```````````````````````````````` example +![](/url) +. + +```````````````````````````````` + + +Reference-style: + +```````````````````````````````` example +![foo][bar] + +[bar]: /url +. + +```````````````````````````````` + + +```````````````````````````````` example +![foo][bar] + +[BAR]: /url +. + +```````````````````````````````` + + +Collapsed: + +```````````````````````````````` example +![foo][] + +[foo]: /url "title" +. + +```````````````````````````````` + + +```````````````````````````````` example +![*foo* bar][] + +[*foo* bar]: /url "title" +. + +```````````````````````````````` + + +The labels are case-insensitive: + +```````````````````````````````` example +![Foo][] + +[foo]: /url "title" +. + +```````````````````````````````` + + +As with reference links, spaces, tabs, and line endings, are not allowed +between the two sets of brackets: + +```````````````````````````````` example +![foo] +[] + +[foo]: /url "title" +. + +[] +```````````````````````````````` + + +Shortcut: + +```````````````````````````````` example +![foo] + +[foo]: /url "title" +. + +```````````````````````````````` + + +```````````````````````````````` example +![*foo* bar] + +[*foo* bar]: /url "title" +. + +```````````````````````````````` + + +Note that link labels cannot contain unescaped brackets: + +```````````````````````````````` example +![[foo]] + +[[foo]]: /url "title" +. +![[foo]] +[[foo]]: /url "title" +```````````````````````````````` + + +The link labels are case-insensitive: + +```````````````````````````````` example +![Foo] + +[foo]: /url "title" +. + +```````````````````````````````` + + +If you just want a literal `!` followed by bracketed text, you can +backslash-escape the opening `[`: + +```````````````````````````````` example +!\[foo] + +[foo]: /url "title" +. +![foo] +```````````````````````````````` + + +If you want a link after a literal `!`, backslash-escape the +`!`: + +```````````````````````````````` example +\![foo] + +[foo]: /url "title" +. +!foo +```````````````````````````````` + + +## Autolinks + +[Autolink](@)s are absolute URIs and email addresses inside +`<` and `>`. They are parsed as links, with the URL or email address +as the link label. + +A [URI autolink](@) consists of `<`, followed by an +[absolute URI] followed by `>`. It is parsed as +a link to the URI, with the URI as the link's label. + +An [absolute URI](@), +for these purposes, consists of a [scheme] followed by a colon (`:`) +followed by zero or more characters other [ASCII control +characters][ASCII control character], [space], `<`, and `>`. +If the URI includes these characters, they must be percent-encoded +(e.g. `%20` for a space). + +For purposes of this spec, a [scheme](@) is any sequence +of 2--32 characters beginning with an ASCII letter and followed +by any combination of ASCII letters, digits, or the symbols plus +("+"), period ("."), or hyphen ("-"). + +Here are some valid autolinks: + +```````````````````````````````` example + +. +http://foo.bar.baz +```````````````````````````````` + + +```````````````````````````````` example + +. +http://foo.bar.baz/test?q=hello&id=22&boolean +```````````````````````````````` + + +```````````````````````````````` example + +. +irc://foo.bar:2233/baz +```````````````````````````````` + + +Uppercase is also fine: + +```````````````````````````````` example + +. +MAILTO:FOO@BAR.BAZ +```````````````````````````````` + + +Note that many strings that count as [absolute URIs] for +purposes of this spec are not valid URIs, because their +schemes are not registered or because of other problems +with their syntax: + +```````````````````````````````` example + +. +a+b+c:d +```````````````````````````````` + + +```````````````````````````````` example + +. +made-up-scheme://foo,bar +```````````````````````````````` + + +```````````````````````````````` example + +. +http://../ +```````````````````````````````` + + +```````````````````````````````` example + +. +localhost:5001/foo +```````````````````````````````` + + +Spaces are not allowed in autolinks: + +```````````````````````````````` example + +. +<http://foo.bar/baz bim> +```````````````````````````````` + + +Backslash-escapes do not work inside autolinks: + +```````````````````````````````` example + +. +http://example.com/\[\ +```````````````````````````````` + + +An [email autolink](@) +consists of `<`, followed by an [email address], +followed by `>`. The link's label is the email address, +and the URL is `mailto:` followed by the email address. + +An [email address](@), +for these purposes, is anything that matches +the [non-normative regex from the HTML5 +spec](https://html.spec.whatwg.org/multipage/forms.html#e-mail-state-(type=email)): + + /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])? + (?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/ + +Examples of email autolinks: + +```````````````````````````````` example + +. +foo@bar.example.com +```````````````````````````````` + + +```````````````````````````````` example + +. +foo+special@Bar.baz-bar0.com +```````````````````````````````` + + +Backslash-escapes do not work inside email autolinks: + +```````````````````````````````` example + +. +<foo+@bar.example.com> +```````````````````````````````` + + +These are not autolinks: + +```````````````````````````````` example +<> +. +<> +```````````````````````````````` + + +```````````````````````````````` example +< http://foo.bar > +. +< http://foo.bar > +```````````````````````````````` + + +```````````````````````````````` example + +. +<m:abc> +```````````````````````````````` + + +```````````````````````````````` example + +. +<foo.bar.baz> +```````````````````````````````` + + +```````````````````````````````` example +http://example.com +. +http://example.com +```````````````````````````````` + + +```````````````````````````````` example +foo@bar.example.com +. +foo@bar.example.com +```````````````````````````````` + + +## Raw HTML + +Text between `<` and `>` that looks like an HTML tag is parsed as a +raw HTML tag and will be rendered in HTML without escaping. +Tag and attribute names are not limited to current HTML tags, +so custom tags (and even, say, DocBook tags) may be used. + +Here is the grammar for tags: + +A [tag name](@) consists of an ASCII letter +followed by zero or more ASCII letters, digits, or +hyphens (`-`). + +An [attribute](@) consists of spaces, tabs, and up to one line ending, +an [attribute name], and an optional +[attribute value specification]. + +An [attribute name](@) +consists of an ASCII letter, `_`, or `:`, followed by zero or more ASCII +letters, digits, `_`, `.`, `:`, or `-`. (Note: This is the XML +specification restricted to ASCII. HTML5 is laxer.) + +An [attribute value specification](@) +consists of optional spaces, tabs, and up to one line ending, +a `=` character, optional spaces, tabs, and up to one line ending, +and an [attribute value]. + +An [attribute value](@) +consists of an [unquoted attribute value], +a [single-quoted attribute value], or a [double-quoted attribute value]. + +An [unquoted attribute value](@) +is a nonempty string of characters not +including spaces, tabs, line endings, `"`, `'`, `=`, `<`, `>`, or `` ` ``. + +A [single-quoted attribute value](@) +consists of `'`, zero or more +characters not including `'`, and a final `'`. + +A [double-quoted attribute value](@) +consists of `"`, zero or more +characters not including `"`, and a final `"`. + +An [open tag](@) consists of a `<` character, a [tag name], +zero or more [attributes], optional spaces, tabs, and up to one line ending, +an optional `/` character, and a `>` character. + +A [closing tag](@) consists of the string ``. + +An [HTML comment](@) consists of ``, +where *text* does not start with `>` or `->`, does not end with `-`, +and does not contain `--`. (See the +[HTML5 spec](http://www.w3.org/TR/html5/syntax.html#comments).) + +A [processing instruction](@) +consists of the string ``, and the string +`?>`. + +A [declaration](@) consists of the string ``, and the character `>`. + +A [CDATA section](@) consists of +the string ``, and the string `]]>`. + +An [HTML tag](@) consists of an [open tag], a [closing tag], +an [HTML comment], a [processing instruction], a [declaration], +or a [CDATA section]. + +Here are some simple open tags: + +```````````````````````````````` example + +. + +```````````````````````````````` + + +Empty elements: + +```````````````````````````````` example + +. + +```````````````````````````````` + + +Whitespace is allowed: + +```````````````````````````````` example + +. + +```````````````````````````````` + + +With attributes: + +```````````````````````````````` example + +. + +```````````````````````````````` + + +Custom tag names can be used: + +```````````````````````````````` example +Foo +. +Foo +```````````````````````````````` + + +Illegal tag names, not parsed as HTML: + +```````````````````````````````` example +<33> <__> +. +<33> <__> +```````````````````````````````` + + +Illegal attribute names: + +```````````````````````````````` example + +. +<a h*#ref="hi"> +```````````````````````````````` + + +Illegal attribute values: + +```````````````````````````````` example + +. +</a href="foo"> +```````````````````````````````` + + +Comments: + +```````````````````````````````` example +foo +. +foo +```````````````````````````````` + + +```````````````````````````````` example +foo +. +foo  +```````````````````````````````` + + +Not comments: + +```````````````````````````````` example +foo foo --> + +foo +. +foo  +foo  +```````````````````````````````` + + +Processing instructions: + +```````````````````````````````` example +foo +. +foo +```````````````````````````````` + + +Declarations: + +```````````````````````````````` example +foo +. +foo +```````````````````````````````` + + +CDATA sections: + +```````````````````````````````` example +foo &<]]> +. +foo &<]]> +```````````````````````````````` + + +Entity and numeric character references are preserved in HTML +attributes: + +```````````````````````````````` example +foo +. +foo +```````````````````````````````` + + +Backslash escapes do not work in HTML attributes: + +```````````````````````````````` example +foo +. +foo +```````````````````````````````` + + +```````````````````````````````` example + +. +<a href="""> +```````````````````````````````` + + +## Hard line breaks + +A line ending (not in a code span or HTML tag) that is preceded +by two or more spaces and does not occur at the end of a block +is parsed as a [hard line break](@) (rendered +in HTML as a ` ` tag): + +```````````````````````````````` example +foo +baz +. +foo +baz +```````````````````````````````` + + +For a more visible alternative, a backslash before the +[line ending] may be used instead of two or more spaces: + +```````````````````````````````` example +foo\ +baz +. +foo +baz +```````````````````````````````` + + +More than two spaces can be used: + +```````````````````````````````` example +foo +baz +. +foo +baz +```````````````````````````````` + + +Leading spaces at the beginning of the next line are ignored: + +```````````````````````````````` example +foo + bar +. +foo +bar +```````````````````````````````` + + +```````````````````````````````` example +foo\ + bar +. +foo +bar +```````````````````````````````` + + +Hard line breaks can occur inside emphasis, links, and other constructs +that allow inline content: + +```````````````````````````````` example +*foo +bar* +. +foo +bar +```````````````````````````````` + + +```````````````````````````````` example +*foo\ +bar* +. +foo +bar +```````````````````````````````` + + +Hard line breaks do not occur inside code spans + +```````````````````````````````` example +`code +span` +. +code span +```````````````````````````````` + + +```````````````````````````````` example +`code\ +span` +. +code\ span +```````````````````````````````` + + +or HTML tags: + +```````````````````````````````` example + +. + +```````````````````````````````` + + +```````````````````````````````` example + +. + +```````````````````````````````` + + +Hard line breaks are for separating inline content within a block. +Neither syntax for hard line breaks works at the end of a paragraph or +other block element: + +```````````````````````````````` example +foo\ +. +foo\ +```````````````````````````````` + + +```````````````````````````````` example +foo +. +foo +```````````````````````````````` + + +```````````````````````````````` example +### foo\ +. +foo\ +```````````````````````````````` + + +```````````````````````````````` example +### foo +. +foo +```````````````````````````````` + + +## Soft line breaks + +A regular line ending (not in a code span or HTML tag) that is not +preceded by two or more spaces or a backslash is parsed as a +[softbreak](@). (A soft line break may be rendered in HTML either as a +[line ending] or as a space. The result will be the same in +browsers. In the examples here, a [line ending] will be used.) + +```````````````````````````````` example +foo +baz +. +foo +baz +```````````````````````````````` + + +Spaces at the end of the line and beginning of the next line are +removed: + +```````````````````````````````` example +foo + baz +. +foo +baz +```````````````````````````````` + + +A conforming parser may render a soft line break in HTML either as a +line ending or as a space. + +A renderer may also provide an option to render soft line breaks +as hard line breaks. + +## Textual content + +Any characters not given an interpretation by the above rules will +be parsed as plain textual content. + +```````````````````````````````` example +hello $.;'there +. +hello $.;'there +```````````````````````````````` + + +```````````````````````````````` example +Foo χρῆν +. +Foo χρῆν +```````````````````````````````` + + +Internal spaces are preserved verbatim: + +```````````````````````````````` example +Multiple spaces +. +Multiple spaces +```````````````````````````````` + + + + +# Appendix: A parsing strategy + +In this appendix we describe some features of the parsing strategy +used in the CommonMark reference implementations. + +## Overview + +Parsing has two phases: + +1. In the first phase, lines of input are consumed and the block +structure of the document---its division into paragraphs, block quotes, +list items, and so on---is constructed. Text is assigned to these +blocks but not parsed. Link reference definitions are parsed and a +map of links is constructed. + +2. In the second phase, the raw text contents of paragraphs and headings +are parsed into sequences of Markdown inline elements (strings, +code spans, links, emphasis, and so on), using the map of link +references constructed in phase 1. + +At each point in processing, the document is represented as a tree of +**blocks**. The root of the tree is a `document` block. The `document` +may have any number of other blocks as **children**. These children +may, in turn, have other blocks as children. The last child of a block +is normally considered **open**, meaning that subsequent lines of input +can alter its contents. (Blocks that are not open are **closed**.) +Here, for example, is a possible document tree, with the open blocks +marked by arrows: + +``` tree +-> document + -> block_quote + paragraph + "Lorem ipsum dolor\nsit amet." + -> list (type=bullet tight=true bullet_char=-) + list_item + paragraph + "Qui *quodsi iracundia*" + -> list_item + -> paragraph + "aliquando id" +``` + +## Phase 1: block structure + +Each line that is processed has an effect on this tree. The line is +analyzed and, depending on its contents, the document may be altered +in one or more of the following ways: + +1. One or more open blocks may be closed. +2. One or more new blocks may be created as children of the + last open block. +3. Text may be added to the last (deepest) open block remaining + on the tree. + +Once a line has been incorporated into the tree in this way, +it can be discarded, so input can be read in a stream. + +For each line, we follow this procedure: + +1. First we iterate through the open blocks, starting with the +root document, and descending through last children down to the last +open block. Each block imposes a condition that the line must satisfy +if the block is to remain open. For example, a block quote requires a +`>` character. A paragraph requires a non-blank line. +In this phase we may match all or just some of the open +blocks. But we cannot close unmatched blocks yet, because we may have a +[lazy continuation line]. + +2. Next, after consuming the continuation markers for existing +blocks, we look for new block starts (e.g. `>` for a block quote). +If we encounter a new block start, we close any blocks unmatched +in step 1 before creating the new block as a child of the last +matched container block. + +3. Finally, we look at the remainder of the line (after block +markers like `>`, list markers, and indentation have been consumed). +This is text that can be incorporated into the last open +block (a paragraph, code block, heading, or raw HTML). + +Setext headings are formed when we see a line of a paragraph +that is a [setext heading underline]. + +Reference link definitions are detected when a paragraph is closed; +the accumulated text lines are parsed to see if they begin with +one or more reference link definitions. Any remainder becomes a +normal paragraph. + +We can see how this works by considering how the tree above is +generated by four lines of Markdown: + +``` markdown +> Lorem ipsum dolor +sit amet. +> - Qui *quodsi iracundia* +> - aliquando id +``` + +At the outset, our document model is just + +``` tree +-> document +``` + +The first line of our text, + +``` markdown +> Lorem ipsum dolor +``` + +causes a `block_quote` block to be created as a child of our +open `document` block, and a `paragraph` block as a child of +the `block_quote`. Then the text is added to the last open +block, the `paragraph`: + +``` tree +-> document + -> block_quote + -> paragraph + "Lorem ipsum dolor" +``` + +The next line, + +``` markdown +sit amet. +``` + +is a "lazy continuation" of the open `paragraph`, so it gets added +to the paragraph's text: + +``` tree +-> document + -> block_quote + -> paragraph + "Lorem ipsum dolor\nsit amet." +``` + +The third line, + +``` markdown +> - Qui *quodsi iracundia* +``` + +causes the `paragraph` block to be closed, and a new `list` block +opened as a child of the `block_quote`. A `list_item` is also +added as a child of the `list`, and a `paragraph` as a child of +the `list_item`. The text is then added to the new `paragraph`: + +``` tree +-> document + -> block_quote + paragraph + "Lorem ipsum dolor\nsit amet." + -> list (type=bullet tight=true bullet_char=-) + -> list_item + -> paragraph + "Qui *quodsi iracundia*" +``` + +The fourth line, + +``` markdown +> - aliquando id +``` + +causes the `list_item` (and its child the `paragraph`) to be closed, +and a new `list_item` opened up as child of the `list`. A `paragraph` +is added as a child of the new `list_item`, to contain the text. +We thus obtain the final tree: + +``` tree +-> document + -> block_quote + paragraph + "Lorem ipsum dolor\nsit amet." + -> list (type=bullet tight=true bullet_char=-) + list_item + paragraph + "Qui *quodsi iracundia*" + -> list_item + -> paragraph + "aliquando id" +``` + +## Phase 2: inline structure + +Once all of the input has been parsed, all open blocks are closed. + +We then "walk the tree," visiting every node, and parse raw +string contents of paragraphs and headings as inlines. At this +point we have seen all the link reference definitions, so we can +resolve reference links as we go. + +``` tree +document + block_quote + paragraph + str "Lorem ipsum dolor" + softbreak + str "sit amet." + list (type=bullet tight=true bullet_char=-) + list_item + paragraph + str "Qui " + emph + str "quodsi iracundia" + list_item + paragraph + str "aliquando id" +``` + +Notice how the [line ending] in the first paragraph has +been parsed as a `softbreak`, and the asterisks in the first list item +have become an `emph`. + +### An algorithm for parsing nested emphasis and links + +By far the trickiest part of inline parsing is handling emphasis, +strong emphasis, links, and images. This is done using the following +algorithm. + +When we're parsing inlines and we hit either + +- a run of `*` or `_` characters, or +- a `[` or `![` + +we insert a text node with these symbols as its literal content, and we +add a pointer to this text node to the [delimiter stack](@). + +The [delimiter stack] is a doubly linked list. Each +element contains a pointer to a text node, plus information about + +- the type of delimiter (`[`, `![`, `*`, `_`) +- the number of delimiters, +- whether the delimiter is "active" (all are active to start), and +- whether the delimiter is a potential opener, a potential closer, + or both (which depends on what sort of characters precede + and follow the delimiters). + +When we hit a `]` character, we call the *look for link or image* +procedure (see below). + +When we hit the end of the input, we call the *process emphasis* +procedure (see below), with `stack_bottom` = NULL. + +#### *look for link or image* + +Starting at the top of the delimiter stack, we look backwards +through the stack for an opening `[` or `![` delimiter. + +- If we don't find one, we return a literal text node `]`. + +- If we do find one, but it's not *active*, we remove the inactive + delimiter from the stack, and return a literal text node `]`. + +- If we find one and it's active, then we parse ahead to see if + we have an inline link/image, reference link/image, compact reference + link/image, or shortcut reference link/image. + + + If we don't, then we remove the opening delimiter from the + delimiter stack and return a literal text node `]`. + + + If we do, then + + * We return a link or image node whose children are the inlines + after the text node pointed to by the opening delimiter. + + * We run *process emphasis* on these inlines, with the `[` opener + as `stack_bottom`. + + * We remove the opening delimiter. + + * If we have a link (and not an image), we also set all + `[` delimiters before the opening delimiter to *inactive*. (This + will prevent us from getting links within links.) + +#### *process emphasis* + +Parameter `stack_bottom` sets a lower bound to how far we +descend in the [delimiter stack]. If it is NULL, we can +go all the way to the bottom. Otherwise, we stop before +visiting `stack_bottom`. + +Let `current_position` point to the element on the [delimiter stack] +just above `stack_bottom` (or the first element if `stack_bottom` +is NULL). + +We keep track of the `openers_bottom` for each delimiter +type (`*`, `_`). Initialize this to `stack_bottom`. + +Then we repeat the following until we run out of potential +closers: + +- Move `current_position` forward in the delimiter stack (if needed) + until we find the first potential closer with delimiter `*` or `_`. + (This will be the potential closer closest + to the beginning of the input -- the first one in parse order.) + +- Now, look back in the stack (staying above `stack_bottom` and + the `openers_bottom` for this delimiter type) for the + first matching potential opener ("matching" means same delimiter). + +- If one is found: + + + Figure out whether we have emphasis or strong emphasis: + if both closer and opener spans have length >= 2, we have + strong, otherwise regular. + + + Insert an emph or strong emph node accordingly, after + the text node corresponding to the opener. + + + Remove any delimiters between the opener and closer from + the delimiter stack. + + + Remove 1 (for regular emph) or 2 (for strong emph) delimiters + from the opening and closing text nodes. If they become empty + as a result, remove them and remove the corresponding element + of the delimiter stack. If the closing node is removed, reset + `current_position` to the next element in the stack. + +- If none is found: + + + Set `openers_bottom` for this delimiter type to the element + before the first potential opener that was rejected solely + because of the "multiple of 3" rule, or to the element + before `current_position`, if there are no such potential + openers. (We know that there are no openers for this kind + of closer up to and including this point, so this puts a + lower bound on future searches.) + + + If the closer at `current_position` is not a potential opener, + remove it from the delimiter stack (since we know it can't + be a closer either). + + + Advance `current_position` to the next element in the stack. + +After we're done, we remove all delimiters above `stack_bottom` from the +delimiter stack. diff --git a/flexmark-test-suite/flexmark-test-suite.iml b/flexmark-test-suite/flexmark-test-suite.iml index f43dac55f..4bc8a456a 100644 --- a/flexmark-test-suite/flexmark-test-suite.iml +++ b/flexmark-test-suite/flexmark-test-suite.iml @@ -9,7 +9,7 @@ - + @@ -35,6 +35,7 @@ + @@ -59,4 +60,4 @@ - \ No newline at end of file + diff --git a/flexmark-test-suite/src/test/java/com/vladsch/flexmark/test/suite/FlexmarkTestSuiteNoDocx.java b/flexmark-test-suite/src/test/java/com/vladsch/flexmark/test/suite/FlexmarkTestSuiteNoDocx.java index 9e2f1a14c..d1f5bdc03 100644 --- a/flexmark-test-suite/src/test/java/com/vladsch/flexmark/test/suite/FlexmarkTestSuiteNoDocx.java +++ b/flexmark-test-suite/src/test/java/com/vladsch/flexmark/test/suite/FlexmarkTestSuiteNoDocx.java @@ -25,6 +25,7 @@ import com.vladsch.flexmark.ext.jekyll.tag.ExtJekyllTagTestSuite; import com.vladsch.flexmark.ext.macros.ExtMacrosTestSuite; import com.vladsch.flexmark.ext.media.tags.ExtMediaTagsTestSuite; +import com.vladsch.flexmark.ext.resizable.image.ExtResizableImageTestSuite; import com.vladsch.flexmark.ext.spec.example.ExtSpecExampleTestSuite; import com.vladsch.flexmark.ext.superscript.ExtSuperscriptTestSuite; import com.vladsch.flexmark.ext.tables.ExtTablesTestSuite; @@ -73,6 +74,7 @@ ExtJekyllTagTestSuite.class, ExtMacrosTestSuite.class, ExtMediaTagsTestSuite.class, + ExtResizableImageTestSuite.class, ExtSpecExampleTestSuite.class, ExtSuperscriptTestSuite.class, ExtTablesTestSuite.class, diff --git a/flexmark-test-util/flexmark-test-util.iml b/flexmark-test-util/flexmark-test-util.iml index 4a04a41fe..f9b578719 100644 --- a/flexmark-test-util/flexmark-test-util.iml +++ b/flexmark-test-util/flexmark-test-util.iml @@ -11,8 +11,12 @@ - - + + + + + + diff --git a/flexmark-test-util/pom.xml b/flexmark-test-util/pom.xml index f8d8fcb29..4b6c75f1a 100644 --- a/flexmark-test-util/pom.xml +++ b/flexmark-test-util/pom.xml @@ -4,7 +4,7 @@ com.vladsch.flexmark flexmark-java - 0.59.100 + 0.64.8 flexmark-test-util @@ -14,7 +14,23 @@ com.vladsch.flexmark - flexmark-util + flexmark-util-misc + + + com.vladsch.flexmark + flexmark-util-data + + + com.vladsch.flexmark + flexmark-util-ast + + + com.vladsch.flexmark + flexmark-util-format + + + com.vladsch.flexmark + flexmark-util-sequence junit @@ -23,7 +39,7 @@ org.jetbrains annotations - 15.0 + 24.0.1 diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/AstCollectingVisitor.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/AstCollectingVisitor.java index e6c1bc797..4a1c25522 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/AstCollectingVisitor.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/AstCollectingVisitor.java @@ -5,7 +5,7 @@ import org.jetbrains.annotations.NotNull; public class AstCollectingVisitor extends NodeVisitorBase { - public static final String EOL = "\n"; + final public static String EOL = "\n"; protected StringBuilder output = new StringBuilder(); protected int indent = 0; protected boolean eolPending = false; diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/DumpTemplateReader.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/DumpTemplateReader.java index e2786898d..17650f58d 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/DumpTemplateReader.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/DumpTemplateReader.java @@ -6,8 +6,8 @@ import java.io.InputStream; class DumpTemplateReader extends TemplateReader { - private final StringBuilder sb = new StringBuilder(); - private final TemplateTestCase testCase; + final private StringBuilder sb = new StringBuilder(); + final private TemplateTestCase testCase; DumpTemplateReader(InputStream stream, TemplateTestCase testCase) { super(stream); diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/ExceptionMatcher.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/ExceptionMatcher.java index 42623c740..0b0d25f4b 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/ExceptionMatcher.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/ExceptionMatcher.java @@ -25,8 +25,13 @@ public boolean matches(Object o) { } } else if (o instanceof Throwable) { if (o.toString().startsWith(prefix)) { + String input; Throwable throwable = (Throwable) o; - String input = throwable.getCause().toString(); + if (throwable.getCause() == null) { + input = o.toString(); + } else { + input = throwable.getCause().toString(); + } return pattern.matcher(input).matches(); } } diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/FlexmarkResourceUrlResolver.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/FlexmarkResourceUrlResolver.java index b975d8632..3232d2f41 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/FlexmarkResourceUrlResolver.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/FlexmarkResourceUrlResolver.java @@ -3,27 +3,46 @@ import com.vladsch.flexmark.test.util.spec.ResourceResolverManager; import com.vladsch.flexmark.test.util.spec.ResourceUrlResolver; -import static com.vladsch.flexmark.test.util.spec.ResourceUrlResolver.isFileProtocol; -import static com.vladsch.flexmark.test.util.spec.ResourceUrlResolver.removeProtocol; - public class FlexmarkResourceUrlResolver { public static void registerUrlResolvers() { - ResourceResolverManager.registerUrlResolver(new TargetTestClassUrlResolver()); + ResourceResolverManager.registerUrlResolver(new TargetTestResourceUrlResolver()); + ResourceResolverManager.registerUrlResolver(new BuildTestResourceUrlResolver()); ResourceResolverManager.registerUrlResolver(new OutTestResourcesUrlResolver()); } - private static class TargetTestClassUrlResolver implements ResourceUrlResolver { - static final String TARGET_TEST_CLASSES = "/target/test-classes/"; + private static class TargetTestResourceUrlResolver implements ResourceUrlResolver { + static final String TEST_RESOURCES = "/target/test-classes/"; + public static final String SRC_TEST_RESOURCES = "/src/test/resources/"; + + TargetTestResourceUrlResolver() { } + + @Override + public String apply(String externalForm) { + if (ResourceUrlResolver.isFileProtocol(externalForm)) { + String noFileProtocol = ResourceUrlResolver.removeProtocol(externalForm); + + if (noFileProtocol.contains(TEST_RESOURCES)) { + return noFileProtocol.replaceFirst(TEST_RESOURCES, SRC_TEST_RESOURCES); + } + } + + return null; + } + } + + private static class BuildTestResourceUrlResolver implements ResourceUrlResolver { + static final String TEST_RESOURCES = "/build/resources/test/"; + public static final String SRC_TEST_RESOURCES = "/src/test/resources/"; - TargetTestClassUrlResolver() {} + BuildTestResourceUrlResolver() { } @Override public String apply(String externalForm) { - if (isFileProtocol(externalForm)) { - String noFileProtocol = removeProtocol(externalForm); + if (ResourceUrlResolver.isFileProtocol(externalForm)) { + String noFileProtocol = ResourceUrlResolver.removeProtocol(externalForm); - if (noFileProtocol.contains(TARGET_TEST_CLASSES)) { - return noFileProtocol.replace(TARGET_TEST_CLASSES, "/src/test/resources/"); + if (noFileProtocol.contains(TEST_RESOURCES)) { + return noFileProtocol.replaceFirst(TEST_RESOURCES, SRC_TEST_RESOURCES); } } @@ -33,19 +52,20 @@ public String apply(String externalForm) { private static class OutTestResourcesUrlResolver implements ResourceUrlResolver { static final String OUT_TEST = "/out/test/"; + public static final String SRC_TEST_RESOURCES = "/src/test/resources/"; - OutTestResourcesUrlResolver() {} + OutTestResourcesUrlResolver() { } @Override public String apply(String externalForm) { - if (isFileProtocol(externalForm)) { - String noFileProtocol = removeProtocol(externalForm); + if (ResourceUrlResolver.isFileProtocol(externalForm)) { + String noFileProtocol = ResourceUrlResolver.removeProtocol(externalForm); int pos = noFileProtocol.indexOf(OUT_TEST); if (pos > 0) { int pathPos = noFileProtocol.indexOf("/", pos + OUT_TEST.length()); if (pathPos > 0) { - return noFileProtocol.substring(0, pos) + "/" + noFileProtocol.substring(pos + OUT_TEST.length(), pathPos) + "/src/test/resources/" + noFileProtocol.substring(pathPos + 1); + return noFileProtocol.substring(0, pos) + "/" + noFileProtocol.substring(pos + OUT_TEST.length(), pathPos) + SRC_TEST_RESOURCES + noFileProtocol.substring(pathPos + 1); } } } diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/FullSpecTestCase.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/FullSpecTestCase.java index 6c17d7536..67f0b36ca 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/FullSpecTestCase.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/FullSpecTestCase.java @@ -17,9 +17,7 @@ protected boolean compoundSections() { return false; } - protected @NotNull ResourceLocation getSpecResourceLocation() { - return ResourceLocation.NULL; - } + abstract protected @NotNull ResourceLocation getSpecResourceLocation(); protected void fullTestSpecStarting() { diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/LoadUnloadDataKeyAggregator.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/LoadUnloadDataKeyAggregator.java index d437f688f..69fc615f9 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/LoadUnloadDataKeyAggregator.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/LoadUnloadDataKeyAggregator.java @@ -8,9 +8,9 @@ import java.util.*; public class LoadUnloadDataKeyAggregator implements DataKeyAggregator { - public static final DataKey>> UNLOAD_EXTENSIONS = new DataKey<>("UNLOAD_EXTENSIONS", Collections.emptyList()); - public static final DataKey> LOAD_EXTENSIONS = new DataKey<>("LOAD_EXTENSIONS", Extension.EMPTY_LIST); - private static final LoadUnloadDataKeyAggregator INSTANCE = new LoadUnloadDataKeyAggregator(); + final public static DataKey>> UNLOAD_EXTENSIONS = new DataKey<>("UNLOAD_EXTENSIONS", Collections.emptyList()); + final public static DataKey> LOAD_EXTENSIONS = new DataKey<>("LOAD_EXTENSIONS", Extension.EMPTY_LIST); + final private static LoadUnloadDataKeyAggregator INSTANCE = new LoadUnloadDataKeyAggregator(); static { DataSet.registerDataKeyAggregator(INSTANCE); } diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/RenderingTestCase.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/RenderingTestCase.java index 284d52525..f4d653471 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/RenderingTestCase.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/RenderingTestCase.java @@ -16,21 +16,21 @@ import static org.junit.Assert.assertEquals; public abstract class RenderingTestCase implements SpecExampleProcessor { - public static final DataKey IGNORE = TestUtils.IGNORE; - public static final DataKey FAIL = TestUtils.FAIL; - public static final DataKey NO_FILE_EOL = TestUtils.NO_FILE_EOL; - public static final DataKey TIMED_ITERATIONS = TestUtils.TIMED_ITERATIONS; - public static final DataKey EMBED_TIMED = TestUtils.EMBED_TIMED; - public static final DataKey TIMED = TestUtils.TIMED; - public static final DataKey INCLUDED_DOCUMENT = TestUtils.INCLUDED_DOCUMENT; - public static final DataKey SOURCE_PREFIX = TestUtils.SOURCE_PREFIX; - public static final DataKey SOURCE_SUFFIX = TestUtils.SOURCE_SUFFIX; - public static final DataKey SOURCE_INDENT = TestUtils.SOURCE_INDENT; - - public static final DataHolder NO_FILE_EOL_FALSE = TestUtils.NO_FILE_EOL_FALSE; - public static final DataKey>> UNLOAD_EXTENSIONS = TestUtils.UNLOAD_EXTENSIONS; - public static final DataKey> LOAD_EXTENSIONS = TestUtils.LOAD_EXTENSIONS; - public static final DataKey> EXTENSIONS = SharedDataKeys.EXTENSIONS; + final public static DataKey IGNORE = TestUtils.IGNORE; + final public static DataKey FAIL = TestUtils.FAIL; + final public static DataKey NO_FILE_EOL = TestUtils.NO_FILE_EOL; + final public static DataKey TIMED_ITERATIONS = TestUtils.TIMED_ITERATIONS; + final public static DataKey EMBED_TIMED = TestUtils.EMBED_TIMED; + final public static DataKey TIMED = TestUtils.TIMED; + final public static DataKey INCLUDED_DOCUMENT = TestUtils.INCLUDED_DOCUMENT; + final public static DataKey SOURCE_PREFIX = TestUtils.SOURCE_PREFIX; + final public static DataKey SOURCE_SUFFIX = TestUtils.SOURCE_SUFFIX; + final public static DataKey SOURCE_INDENT = TestUtils.SOURCE_INDENT; + + final public static DataHolder NO_FILE_EOL_FALSE = TestUtils.NO_FILE_EOL_FALSE; + final public static DataKey>> UNLOAD_EXTENSIONS = TestUtils.UNLOAD_EXTENSIONS; + final public static DataKey> LOAD_EXTENSIONS = TestUtils.LOAD_EXTENSIONS; + final public static DataKey> EXTENSIONS = SharedDataKeys.EXTENSIONS; @Rule public ExpectedException thrown = ExpectedException.none(); diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SettableExtractedInstance.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SettableExtractedInstance.java index 58f8da155..a32bb0535 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SettableExtractedInstance.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SettableExtractedInstance.java @@ -19,8 +19,8 @@ * @param type for the setting */ final public class SettableExtractedInstance { - private final @NotNull DataKey> myConsumerKey; - private final @NotNull Function myDataExtractor; + final private @NotNull DataKey> myConsumerKey; + final private @NotNull Function myDataExtractor; public SettableExtractedInstance(@NotNull DataKey> consumerKey, @NotNull Function dataExtractor) { myConsumerKey = consumerKey; diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SettableInstance.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SettableInstance.java index 5d06fdb14..71321ac92 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SettableInstance.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SettableInstance.java @@ -19,8 +19,8 @@ * @param type for the setting */ final public class SettableInstance { - private final @NotNull DataKey> myConsumerKey; - private final @Nullable Collection> myExtractedInstanceSetters; + final private @NotNull DataKey> myConsumerKey; + final private @Nullable Collection> myExtractedInstanceSetters; public SettableInstance(@NotNull DataKey> consumerKey, @NotNull Collection> extractedInstanceSetters) { myConsumerKey = consumerKey; diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SpecExampleParse.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SpecExampleParse.java index 93ad70e59..b6020d177 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SpecExampleParse.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/SpecExampleParse.java @@ -84,7 +84,7 @@ public String parse(String source) { myStartTime = System.nanoTime(); - myRenderer.parse(input); + myRenderer.parse(input.toString()); for (int i = 1; i < myIterations; i++) myRenderer.parse(input); myParseTime = System.nanoTime(); diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/TemplateTestCase.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/TemplateTestCase.java index b7e4e827e..dfffbea49 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/TemplateTestCase.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/TemplateTestCase.java @@ -8,7 +8,7 @@ import java.io.InputStream; public abstract class TemplateTestCase implements TemplateReaderFactory { - public static final String SPEC_RESOURCE = "/template.txt"; + final public static String SPEC_RESOURCE = "/template.txt"; private DumpTemplateReader dumpTemplateReader; diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/TestUtils.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/TestUtils.java index 5d8469755..3cebb13a2 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/TestUtils.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/TestUtils.java @@ -32,51 +32,51 @@ import static com.vladsch.flexmark.util.sequence.SequenceUtils.*; public class TestUtils { - public static final char MARKUP_CARET_CHAR = '⦙'; - public static final char MARKUP_SELECTION_START_CHAR = '⟦'; - public static final char MARKUP_SELECTION_END_CHAR = '⟧'; - public static final String MARKUP_CARET = Character.toString(MARKUP_CARET_CHAR); - public static final String MARKUP_SELECTION_START = Character.toString(MARKUP_SELECTION_START_CHAR); - public static final String MARKUP_SELECTION_END = Character.toString(MARKUP_SELECTION_END_CHAR); - public static final @NotNull CharPredicate CARET_PREDICATE = CharPredicate.anyOf(MARKUP_CARET_CHAR); - public static final @NotNull CharPredicate MARKUP_PREDICATE = CharPredicate.anyOf(MARKUP_CARET_CHAR, MARKUP_SELECTION_START_CHAR, MARKUP_SELECTION_END_CHAR); - public static final int[] EMPTY_OFFSETS = new int[0]; + final public static char MARKUP_CARET_CHAR = '⦙'; + final public static char MARKUP_SELECTION_START_CHAR = '⟦'; + final public static char MARKUP_SELECTION_END_CHAR = '⟧'; + final public static String MARKUP_CARET = Character.toString(MARKUP_CARET_CHAR); + final public static String MARKUP_SELECTION_START = Character.toString(MARKUP_SELECTION_START_CHAR); + final public static String MARKUP_SELECTION_END = Character.toString(MARKUP_SELECTION_END_CHAR); + final public static @NotNull CharPredicate CARET_PREDICATE = CharPredicate.anyOf(MARKUP_CARET_CHAR); + final public static @NotNull CharPredicate MARKUP_PREDICATE = CharPredicate.anyOf(MARKUP_CARET_CHAR, MARKUP_SELECTION_START_CHAR, MARKUP_SELECTION_END_CHAR); + final public static int[] EMPTY_OFFSETS = new int[0]; static { // CAUTION: need to register our url resolvers FlexmarkResourceUrlResolver.registerUrlResolvers(); } - public static final char DISABLED_OPTION_PREFIX_CHAR = '-'; - public static final String DISABLED_OPTION_PREFIX = String.valueOf(DISABLED_OPTION_PREFIX_CHAR); + final public static char DISABLED_OPTION_PREFIX_CHAR = '-'; + final public static String DISABLED_OPTION_PREFIX = String.valueOf(DISABLED_OPTION_PREFIX_CHAR); - public static final String EMBED_TIMED_OPTION_NAME = "EMBED_TIMED"; - public static final String FAIL_OPTION_NAME = "FAIL"; - public static final String FILE_EOL_OPTION_NAME = "FILE_EOL"; - public static final String IGNORE_OPTION_NAME = "IGNORE"; - public static final String NO_FILE_EOL_OPTION_NAME = "NO_FILE_EOL"; - public static final String TIMED_ITERATIONS_OPTION_NAME = "TIMED_ITERATIONS"; - public static final String TIMED_OPTION_NAME = "TIMED"; + final public static String EMBED_TIMED_OPTION_NAME = "EMBED_TIMED"; + final public static String FAIL_OPTION_NAME = "FAIL"; + final public static String FILE_EOL_OPTION_NAME = "FILE_EOL"; + final public static String IGNORE_OPTION_NAME = "IGNORE"; + final public static String NO_FILE_EOL_OPTION_NAME = "NO_FILE_EOL"; + final public static String TIMED_ITERATIONS_OPTION_NAME = "TIMED_ITERATIONS"; + final public static String TIMED_OPTION_NAME = "TIMED"; - public static final DataKey EMBED_TIMED = new DataKey<>(TIMED_OPTION_NAME, false); - public static final DataKey FAIL = new DataKey<>(FAIL_OPTION_NAME, false); - public static final DataKey IGNORE = new DataKey<>(IGNORE_OPTION_NAME, false); - public static final DataKey NO_FILE_EOL = new DataKey<>(NO_FILE_EOL_OPTION_NAME, true); - public static final DataKey TIMED = new DataKey<>(TIMED_OPTION_NAME, false); - public static final DataKey TIMED_ITERATIONS = new DataKey<>(TIMED_ITERATIONS_OPTION_NAME, 100); + final public static DataKey EMBED_TIMED = new DataKey<>(TIMED_OPTION_NAME, false); + final public static DataKey FAIL = new DataKey<>(FAIL_OPTION_NAME, false); + final public static DataKey IGNORE = new DataKey<>(IGNORE_OPTION_NAME, false); + final public static DataKey NO_FILE_EOL = new DataKey<>(NO_FILE_EOL_OPTION_NAME, true); + final public static DataKey TIMED = new DataKey<>(TIMED_OPTION_NAME, false); + final public static DataKey TIMED_ITERATIONS = new DataKey<>(TIMED_ITERATIONS_OPTION_NAME, 100); - public static final String TIMED_FORMAT_STRING = "Timing %s: parse %.3f ms, render %.3f ms, total %.3f\n"; + final public static String TIMED_FORMAT_STRING = "Timing %s: parse %.3f ms, render %.3f ms, total %.3f\n"; - public static final DataKey INCLUDED_DOCUMENT = new DataKey<>("INCLUDED_DOCUMENT", ""); - public static final DataKey SOURCE_PREFIX = new DataKey<>("SOURCE_PREFIX", ""); - public static final DataKey SOURCE_SUFFIX = new DataKey<>("SOURCE_SUFFIX", ""); - public static final DataKey SOURCE_INDENT = new DataKey<>("SOURCE_INDENT", ""); + final public static DataKey INCLUDED_DOCUMENT = new DataKey<>("INCLUDED_DOCUMENT", ""); + final public static DataKey SOURCE_PREFIX = new DataKey<>("SOURCE_PREFIX", ""); + final public static DataKey SOURCE_SUFFIX = new DataKey<>("SOURCE_SUFFIX", ""); + final public static DataKey SOURCE_INDENT = new DataKey<>("SOURCE_INDENT", ""); - public static final DataHolder NO_FILE_EOL_FALSE = new MutableDataSet().set(NO_FILE_EOL, false).toImmutable(); - public static final DataKey>> UNLOAD_EXTENSIONS = LoadUnloadDataKeyAggregator.UNLOAD_EXTENSIONS; - public static final DataKey> LOAD_EXTENSIONS = LoadUnloadDataKeyAggregator.LOAD_EXTENSIONS; + final public static DataHolder NO_FILE_EOL_FALSE = new MutableDataSet().set(NO_FILE_EOL, false).toImmutable(); + final public static DataKey>> UNLOAD_EXTENSIONS = LoadUnloadDataKeyAggregator.UNLOAD_EXTENSIONS; + final public static DataKey> LOAD_EXTENSIONS = LoadUnloadDataKeyAggregator.LOAD_EXTENSIONS; final private static DataHolder EMPTY_OPTIONS = new DataSet(); final public static DataKey> CUSTOM_OPTION = new DataKey<>("CUSTOM_OPTION", (option, params) -> EMPTY_OPTIONS); - public static final String FILE_PROTOCOL = ResourceUrlResolver.FILE_PROTOCOL; + final public static String FILE_PROTOCOL = ResourceUrlResolver.FILE_PROTOCOL; public static DataHolder processOption(@NotNull Map optionsMap, @NotNull String option) { DataHolder dataHolder = null; @@ -125,7 +125,6 @@ public static HashMap buildOptionsMap(@NotNull String[] options, * Each row is passed to factory to allow creating custom options. * @param factory factory creating a type from ExampleOption and given row of parameters * @param type of value in the map - * * @return constructed hash map of option name */ @NotNull @@ -159,7 +158,7 @@ public static HashMap buildOptionsMap(boolean ensureAllBuiltInPre @NotNull public static Pair addSpecSection(@NotNull String headingLine, @NotNull String headingText, String[] sectionHeadings) { assert sectionHeadings.length == 7; - int lastSectionLevel = Math.max(1, Math.min(6, RichSequence.of(headingLine).countLeading(SequenceUtils.HASH_SET))); + int lastSectionLevel = Math.max(1, Math.min(6, RichSequence.of(headingLine).countLeading(CharPredicate.HASH))); sectionHeadings[lastSectionLevel] = headingText; int iMax = 7; for (int i = lastSectionLevel + 1; i < iMax; i++) { @@ -189,7 +188,6 @@ public static Pair addSpecSection(@NotNull String headingLine, * @param example spec example instance for which options are being processed * @param optionSets comma separate list of option set names * @param optionsProvider function to take a string option name and provide settings based on it - * * @return combined set from applying these options together */ public static DataHolder getOptions(@NotNull SpecExample example, @Nullable String optionSets, @NotNull Function optionsProvider) { @@ -444,9 +442,7 @@ public static void addSpecExample( /** * @param s text to convert to visible chars - * * @return spec test special chars converted to visible - * * @deprecated use {@link #toVisibleSpecText(String)} */ @Deprecated @@ -456,7 +452,6 @@ public static String showTabs(String s) { /** * @param s text to convert to visible chars - * * @return spec test special chars converted to visible */ public static String toVisibleSpecText(String s) { @@ -467,7 +462,6 @@ public static String toVisibleSpecText(String s) { /** * @param s text to convert to visible chars - * * @return spec test special chars converted to visible */ public static CharSequence toVisibleSpecText(CharSequence s) { @@ -477,16 +471,14 @@ public static CharSequence toVisibleSpecText(CharSequence s) { return sequence .replace("\u2192", "࢐").replace("\t", "\u2192") .replace("\u23ae", "ae;").replace("\u001f", "\u23ae") - .replace("\u23ce", "ce").replace("\r", "\u23ce") - .replace("\u27a5", "a5").replace(SequenceUtils.LINE_SEP, "\u27a5") + .replace("\u23ce", "ce;").replace("\r", "\u23ce") + .replace("\u27a5", "a5;").replace(SequenceUtils.LINE_SEP, "\u27a5") ; } /** * @param s text to convert to from visible chars to normal - * * @return spec test special visible chars converted to normal - * * @deprecated use {@link #fromVisibleSpecText(String)} */ @Deprecated @@ -496,17 +488,25 @@ public static String unShowTabs(String s) { /** * @param s text to convert to from visible chars to normal - * * @return spec test special visible chars converted to normal */ public static String fromVisibleSpecText(String s) { if (s == null) return ""; - // Tabs are shown as "rightwards arrow" for easier comparison and IntelliJ dummy identifier as ⎮ - return s - .replace("\u27a5", SequenceUtils.LINE_SEP).replace("a5", "\u27a5") - .replace("\u23ce", "\r").replace("ce", "\u23ce") + return fromVisibleSpecText((CharSequence) s).toString(); + } + + /** + * @param s text to convert to from visible chars to normal + * @return spec test special visible chars converted to normal + */ + public static CharSequence fromVisibleSpecText(CharSequence s) { + if (s == null) return ""; + BasedSequence sequence = BasedSequence.of(s); + return sequence + .replace("\u27a5", SequenceUtils.LINE_SEP).replace("a5;", "\u27a5") + .replace("\u23ce", "\r").replace("ce;", "\u23ce") .replace("\u23ae", "\u001f").replace("ae;", "\u23ae") - .replace('\u2192', '\t').replace("࢐", "\u2192") + .replace("\u2192", "\t").replace("࢐", "\u2192") ; } diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/IParseBase.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/IParseBase.java index 182362f3a..bff1a3bc6 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/IParseBase.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/IParseBase.java @@ -13,7 +13,7 @@ import java.io.Reader; public abstract class IParseBase implements IParse { - private final DataHolder myOptions; + final private DataHolder myOptions; public IParseBase() { this(null); @@ -47,8 +47,8 @@ public boolean transferReferences(@NotNull Document document, @NotNull Document while (true) { int charsRead = bufferedReader.read(buffer); + if (charsRead < 0) break; file.append(buffer, 0, charsRead); - if (charsRead < buffer.length) break; } BasedSequence source = BasedSequence.of(file.toString()); diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/IRenderBase.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/IRenderBase.java index 159832af1..0a4439348 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/IRenderBase.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/IRenderBase.java @@ -9,14 +9,14 @@ import java.io.IOException; public abstract class IRenderBase implements IRender { - public static final IRender NullRenderer = new IRenderBase() { + public static final IRender NULL_RENDERER = new IRenderBase() { @Override public void render(@NotNull Node document, @NotNull Appendable output) { } }; - public static final IRender TextRenderer = new IRenderBase() { + public static final IRender TEXT_RENDERER = new IRenderBase() { @Override public void render(@NotNull Node document, @NotNull Appendable output) { try { @@ -27,7 +27,10 @@ public void render(@NotNull Node document, @NotNull Appendable output) { } }; - private final DataHolder myOptions; + @Deprecated public static final IRender NullRenderer = NULL_RENDERER; + @Deprecated public static final IRender TextRenderer = TEXT_RENDERER; + + final private DataHolder myOptions; public IRenderBase() { this(null); diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceLocation.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceLocation.java index 0f161cbb3..e3897daaa 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceLocation.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceLocation.java @@ -4,14 +4,11 @@ import com.vladsch.flexmark.test.util.TestUtils; import org.jetbrains.annotations.NotNull; -import java.io.BufferedReader; -import java.io.IOException; -import java.io.InputStream; -import java.io.InputStreamReader; +import java.io.*; import java.nio.charset.StandardCharsets; public class ResourceLocation { - public static final ResourceLocation NULL = of(Object.class, "", ""); + final public static ResourceLocation NULL = of(Object.class, "", ""); final private @NotNull Class resourceClass; final private @NotNull String resourcePath; @@ -44,6 +41,15 @@ public String getFileUrl() { return fileUrl; } + @NotNull + public String getFileDirectoryUrl() { + int pos = fileUrl.lastIndexOf(File.separatorChar); + if (pos > 0) { + return fileUrl.substring(0, pos + 1); + } + return fileUrl; + } + @NotNull public String getFileUrl(int lineNumber) { return TestUtils.getUrlWithLineNumber(getFileUrl(), lineNumber); diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceResolverManager.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceResolverManager.java index cd5579b59..5d3a7dd0c 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceResolverManager.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceResolverManager.java @@ -11,8 +11,12 @@ import static com.vladsch.flexmark.test.util.spec.ResourceUrlResolver.hasProtocol; public class ResourceResolverManager { - private final static ArrayList> urlResolvers = new ArrayList<>(); - + /** + * urlResolvers map test resource location url to source resource url to allow tests to + * output file URLs which refer to source location, not copies in test location + */ + final private static ArrayList> urlResolvers = new ArrayList<>(); + public static void registerUrlResolver(@NotNull Function resolver) { ResourceResolverManager.urlResolvers.add(resolver); } diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceUrlResolver.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceUrlResolver.java index b7a11f1f5..b9885a044 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceUrlResolver.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/ResourceUrlResolver.java @@ -4,6 +4,9 @@ import java.util.function.Function; +/** + * Used to resolve test resource URL from copy in test location to URL of source file + */ public interface ResourceUrlResolver extends Function { @Override String apply(String externalForm); diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/SpecExample.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/SpecExample.java index 4d4d66f2d..40008089a 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/SpecExample.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/SpecExample.java @@ -12,18 +12,18 @@ import java.util.concurrent.ConcurrentMap; public class SpecExample { - public static final SpecExample NULL = new SpecExample(ResourceLocation.NULL, 0, null, "", 0, "", "", null, null, true); - - private final @NotNull ResourceLocation resourceLocation; - private final int lineNumber; - private final @Nullable String optionsSet; - private final @Nullable String section; - private final int exampleNumber; - private final @NotNull String source; - private final @NotNull String html; - private final @Nullable String ast; - private final @Nullable String comment; - private final boolean isNull; + final public static SpecExample NULL = new SpecExample(ResourceLocation.NULL, 0, null, "", 0, "", "", null, null, true); + + final private @NotNull ResourceLocation resourceLocation; + final private int lineNumber; + final private @Nullable String optionsSet; + final private @Nullable String section; + final private int exampleNumber; + final private @NotNull String source; + final private @NotNull String html; + final private @Nullable String ast; + final private @Nullable String comment; + final private boolean isNull; public SpecExample(@NotNull ResourceLocation resourceLocation, int lineNumber, @Nullable String optionsSet, @Nullable String section, int exampleNumber, @NotNull String source, @NotNull String html, @Nullable String ast, String comment) { this(resourceLocation, lineNumber, optionsSet, section, exampleNumber, source, html, ast, comment, false); diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/SpecReader.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/SpecReader.java index 524d295f1..18047998b 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/SpecReader.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/SpecReader.java @@ -17,17 +17,17 @@ import static com.vladsch.flexmark.test.util.spec.SpecReader.State.COMMENT; public class SpecReader { - public static final String EXAMPLE_KEYWORD = "example"; - public static final String EXAMPLE_BREAK = "````````````````````````````````"; - public static final String EXAMPLE_START = EXAMPLE_BREAK + " " + EXAMPLE_KEYWORD; - public static final String EXAMPLE_START_NBSP = EXAMPLE_BREAK + "\u00A0" + EXAMPLE_KEYWORD; - public static final String EXAMPLE_TEST_BREAK = "````````````````"; - public static final String EXAMPLE_TEST_START = EXAMPLE_TEST_BREAK + " " + EXAMPLE_KEYWORD; - public static final String OPTIONS_KEYWORD = "options"; - public static final String OPTIONS_STRING = " " + OPTIONS_KEYWORD; - public static final Pattern OPTIONS_PATTERN = Pattern.compile(".*(?:\\s|\u00A0)\\Q" + OPTIONS_KEYWORD + "\\E(?:\\s|\u00A0)*\$(?:\\s|\u00A0)*(.*)(?:\\s|\u00A0)*\$(?:\\s|\u00A0)*"); - public static final String SECTION_BREAK = "."; - public static final String SECTION_TEST_BREAK = "…"; + final public static String EXAMPLE_KEYWORD = "example"; + final public static String EXAMPLE_BREAK = "````````````````````````````````"; + final public static String EXAMPLE_START = EXAMPLE_BREAK + " " + EXAMPLE_KEYWORD; + final public static String EXAMPLE_START_NBSP = EXAMPLE_BREAK + "\u00A0" + EXAMPLE_KEYWORD; + final public static String EXAMPLE_TEST_BREAK = "````````````````"; + final public static String EXAMPLE_TEST_START = EXAMPLE_TEST_BREAK + " " + EXAMPLE_KEYWORD; + final public static String OPTIONS_KEYWORD = "options"; + final public static String OPTIONS_STRING = " " + OPTIONS_KEYWORD; + final public static Pattern OPTIONS_PATTERN = Pattern.compile(".*(?:\\s|\u00A0)\\Q" + OPTIONS_KEYWORD + "\\E(?:\\s|\u00A0)*\$(?:\\s|\u00A0)*(.*)(?:\\s|\u00A0)*\$(?:\\s|\u00A0)*"); + final public static String SECTION_BREAK = "."; + final public static String SECTION_TEST_BREAK = "…"; protected static final Pattern SECTION_PATTERN = Pattern.compile("#{1,6} +(.*)"); protected final @NotNull InputStream inputStream; @@ -227,7 +227,7 @@ protected void processLine(String line) { if (!lineAbsorbed) { if (lineProcessed) { comment = null; - } else if (section != null) { + } else if (section != null && state == State.BEFORE) { if (comment == null) comment = new StringBuilder(); comment.append(line).append('\n'); } diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/TemplateEntry.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/TemplateEntry.java index 0f2f12204..b2a29b7e8 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/TemplateEntry.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/TemplateEntry.java @@ -7,11 +7,11 @@ import java.util.regex.Pattern; public class TemplateEntry { - private final int entryNumber; - private final String source; - private final HashSet params = new HashSet<>(); + final private int entryNumber; + final private String source; + final private HashSet params = new HashSet<>(); - private static final Pattern PARAMETER_PATTERN = Pattern.compile("\\$[a-zA-Z_]+\\$"); + final private static Pattern PARAMETER_PATTERN = Pattern.compile("\\$[a-zA-Z_]+\\$"); public TemplateEntry(int entryNumber, String source) { this.entryNumber = entryNumber; diff --git a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/TemplateReader.java b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/TemplateReader.java index 5b1f4b178..489b90091 100644 --- a/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/TemplateReader.java +++ b/flexmark-test-util/src/main/java/com/vladsch/flexmark/test/util/spec/TemplateReader.java @@ -9,8 +9,8 @@ import java.util.List; public class TemplateReader { - public static final String ENTRY_START = "```````````````````````````````` template"; - public static final String ENTRY_BREAK = "````````````````````````````````"; + final public static String ENTRY_START = "```````````````````````````````` template"; + final public static String ENTRY_BREAK = "````````````````````````````````"; protected final InputStream inputStream; diff --git a/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/LoadUnloadDataKeyAggregatorTest.java b/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/LoadUnloadDataKeyAggregatorTest.java index aba723b97..2c5664733 100644 --- a/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/LoadUnloadDataKeyAggregatorTest.java +++ b/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/LoadUnloadDataKeyAggregatorTest.java @@ -12,7 +12,7 @@ import static org.junit.Assert.assertEquals; public class LoadUnloadDataKeyAggregatorTest { - public static final DataKey>> LOAD_EXTENSION_CLASSES = new DataKey<>("LOAD_EXTENSION_CLASSES", Collections.emptyList()); + final public static DataKey>> LOAD_EXTENSION_CLASSES = new DataKey<>("LOAD_EXTENSION_CLASSES", Collections.emptyList()); final static HashMap optionsMap = new HashMap<>(); static { diff --git a/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/TestUtilsTest.java b/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/TestUtilsTest.java index 8946fd73b..4b1c4b409 100644 --- a/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/TestUtilsTest.java +++ b/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/TestUtilsTest.java @@ -34,4 +34,30 @@ public void test_extractMarkup() { assertEquals(pairToString(Pair.of("With markups", new int[] { 7, 11, 14 })), pairToString(TestUtils.extractMarkup(BasedSequence.of("⟦ ⟧With ⦙mark⦙ups⦙")))); assertEquals(pairToString(Pair.of("With markups\nMore markups", new int[] { 7, 11, 14, 22, 26, 29 })), pairToString(TestUtils.extractMarkup(BasedSequence.of("⟦ ⟧With ⦙mark⦙ups⦙\n⟦ ⟧More ⦙mark⦙ups⦙")))); } + + @Test + public void test_toVisibleSpace() { + assertEquals("\u2192", TestUtils.toVisibleSpecText("\t")); + assertEquals("\u23ae", TestUtils.toVisibleSpecText("\u001f")); + assertEquals("\u23ce", TestUtils.toVisibleSpecText("\r")); + assertEquals("\u27a5", TestUtils.toVisibleSpecText("\u2028")); + + assertEquals("࢐", TestUtils.toVisibleSpecText("\u2192")); + assertEquals("ae;", TestUtils.toVisibleSpecText("\u23ae")); + assertEquals("ce;", TestUtils.toVisibleSpecText("\u23ce")); + assertEquals("a5;", TestUtils.toVisibleSpecText("\u27a5")); + } + + @Test + public void test_fromVisibleSpace() { + assertEquals("\t", TestUtils.fromVisibleSpecText("\u2192")); + assertEquals("\u001f", TestUtils.fromVisibleSpecText("\u23ae")); + assertEquals("\r", TestUtils.fromVisibleSpecText("\u23ce")); + assertEquals("\u2028", TestUtils.fromVisibleSpecText("\u27a5")); + + assertEquals("\u2192", TestUtils.fromVisibleSpecText("࢐")); + assertEquals("\u23ae", TestUtils.fromVisibleSpecText("ae;")); + assertEquals("\u23ce", TestUtils.fromVisibleSpecText("ce;")); + assertEquals("\u27a5", TestUtils.fromVisibleSpecText("a5;")); + } } diff --git a/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/TestUtilsTestSuite.java b/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/TestUtilsTestSuite.java index 72fa370dc..2b9459290 100644 --- a/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/TestUtilsTestSuite.java +++ b/flexmark-test-util/src/test/java/com/vladsch/flexmark/test/util/TestUtilsTestSuite.java @@ -6,6 +6,7 @@ @RunWith(Suite.class) @Suite.SuiteClasses({ LoadUnloadDataKeyAggregatorTest.class, + TestUtilsTest.class }) public class TestUtilsTestSuite { } diff --git a/flexmark-tree-iteration/README.md b/flexmark-tree-iteration/README.md index 363f5749a..49410b723 100644 --- a/flexmark-tree-iteration/README.md +++ b/flexmark-tree-iteration/README.md @@ -4,7 +4,6 @@ flexmark-tree-iteration **tree-iteration-util** Used to iterate, including recursively, over tree structure elements using node class or value filters. - ### Requirements * Java 8 or above @@ -13,9 +12,7 @@ using node class or value filters. * `org.slf4j:slf4j-api:1.7.25` library. * `org.jetbrains:annotations:15.0` library. -### master [![Build status](https://travis-ci.org/vsch/flexmark-java.svg?branch=master)](https://travis-ci.org/vsch/flexmark-java) - -### latest [![Maven Central status](https://img.shields.io/maven-central/v/com.vladsch.flexmark/flexmark.svg)](https://search.maven.org/search?q=g:com.vladsch.flexmark) [![Build status](https://travis-ci.org/vsch/flexmark-java.svg?branch=0.50.40)](https://travis-ci.org/vsch/flexmark-java) [![Javadocs](https://www.javadoc.io/badge/com.vladsch.flexmark/flexmark.svg)](https://www.javadoc.io/doc/com.vladsch.flexmark/flexmark) +### latest [![Maven Central status](https://img.shields.io/maven-central/v/com.vladsch.flexmark/flexmark.svg)](https://search.maven.org/search?q=g:com.vladsch.flexmark) [![Javadocs](https://www.javadoc.io/badge/com.vladsch.flexmark/flexmark.svg)](https://www.javadoc.io/doc/com.vladsch.flexmark/flexmark) ### Examples: @@ -60,16 +57,5 @@ Copyright (c) 2019, Vladimir Schneider , BSD (2-clause) licensed, see [LICENSE.txt] file. [LICENSE.txt]: ../LICENSE.txt -[All about me]: https://vladsch.com/about -[Android Studio]: https://developer.android.com/sdk/installing/studio.html -[GitHub Issues page]: https://github.com/vsch/tree-iteration/issues -[LICENSE]: LICENSE.txt -[Markdown Navigator]: http://vladsch.com/product/markdown-navigator -[Maven Central status]: https://img.shields.io/maven-central/v/com.vladsch.tree-iteration/tree-iteration.svg -[Mia: Missing In Actions]: https://plugins.jetbrains.com/idea/plugin/9257-missing-in-actions -[MultiMarkdown]: https://fletcherpenney.net/multimarkdown/ -[Semantic Versioning]: https://semver.org/ -[tree-iteration]: https://github.com/vsch/tree-iteration -[tree-iteration on Maven]: https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.vladsch.tree-iteration%22 -[tree-iteration wiki]: https://github.com/vsch/tree-iteration/wiki +[tree-iteration on Maven]: https://central.sonatype.com/search?q=g%3Acom.vladsch.tree-iteration&smo=true diff --git a/flexmark-tree-iteration/flexmark-tree-iteration.iml b/flexmark-tree-iteration/flexmark-tree-iteration.iml index 5c9215c67..7371edfa1 100644 --- a/flexmark-tree-iteration/flexmark-tree-iteration.iml +++ b/flexmark-tree-iteration/flexmark-tree-iteration.iml @@ -23,12 +23,15 @@ + - + + + - + diff --git a/flexmark-tree-iteration/pom.xml b/flexmark-tree-iteration/pom.xml index a02b027dd..a0f87c20e 100644 --- a/flexmark-tree-iteration/pom.xml +++ b/flexmark-tree-iteration/pom.xml @@ -4,7 +4,7 @@ com.vladsch.flexmark flexmark-java - 0.59.100 + 0.64.8 flexmark-tree-iteration @@ -15,11 +15,19 @@ org.jetbrains annotations - 15.0 + 24.0.1 - + + com.vladsch.flexmark + flexmark-util-ast + + + com.vladsch.flexmark + flexmark-util-data + + com.vladsch.flexmark - flexmark-util + flexmark-util-collection org.slf4j diff --git a/flexmark-tree-iteration/src/main/java/com/vladsch/flexmark/tree/iteration/IteratorInstance.java b/flexmark-tree-iteration/src/main/java/com/vladsch/flexmark/tree/iteration/IteratorInstance.java index 830843570..b9445283b 100644 --- a/flexmark-tree-iteration/src/main/java/com/vladsch/flexmark/tree/iteration/IteratorInstance.java +++ b/flexmark-tree-iteration/src/main/java/com/vladsch/flexmark/tree/iteration/IteratorInstance.java @@ -10,15 +10,15 @@ import java.util.function.Predicate; final public class IteratorInstance implements ValueIteration { - final static private Logger LOG = TreeIterator.LOG; + // final static private Logger LOG = TreeIterator.LOG; final static private Logger LOG_INFO = TreeIterator.LOG_INFO; final static private Logger LOG_TRACE = TreeIterator.LOG_TRACE; private Iteration myIteration; // current iteration information private @Nullable Stack> myRecursions; // recursion frames - final @NotNull private IterationConditions myIterationConditions; - final @NotNull private Predicate myRecursionPredicate; - final @NotNull private Predicate myFilterPredicate; + final private @NotNull IterationConditions myIterationConditions; + final private @NotNull Predicate myRecursionPredicate; + final private @NotNull Predicate myFilterPredicate; private int myTotalLoopCount = 0; // total looping count across all nesting levels, including filtered out elements private int myTotalAcceptCount = 0; // total looping count across all nesting levels, only consumed elements private @Nullable N myMatch; @@ -173,7 +173,6 @@ public void doReturn() { } private void dropRecursions(int iteration, boolean inclusive) { - int iterationIndex = iteration < 0 ? getRecursionLevel() + iteration : iteration; if (inclusive) iteration++; if (iteration > 0) { diff --git a/flexmark-tree-iteration/src/main/java/com/vladsch/flexmark/tree/iteration/TreeIterator.java b/flexmark-tree-iteration/src/main/java/com/vladsch/flexmark/tree/iteration/TreeIterator.java index 864533ed6..181cad657 100644 --- a/flexmark-tree-iteration/src/main/java/com/vladsch/flexmark/tree/iteration/TreeIterator.java +++ b/flexmark-tree-iteration/src/main/java/com/vladsch/flexmark/tree/iteration/TreeIterator.java @@ -8,16 +8,16 @@ import java.util.function.Predicate; public class TreeIterator { - public final static Logger LOG = LoggerFactory.getILoggerFactory().getLogger("com.vladsch.treeIteration.util.looping"); - public final static Logger LOG_INFO = LoggerFactory.getILoggerFactory().getLogger("com.vladsch.treeIteration.util.looping-summary"); - public final static Logger LOG_TRACE = LoggerFactory.getILoggerFactory().getLogger("com.vladsch.treeIteration.util.looping-detailed"); + final public static Logger LOG = LoggerFactory.getILoggerFactory().getLogger("com.vladsch.treeIteration.util.looping"); + final public static Logger LOG_INFO = LoggerFactory.getILoggerFactory().getLogger("com.vladsch.treeIteration.util.looping-summary"); + final public static Logger LOG_TRACE = LoggerFactory.getILoggerFactory().getLogger("com.vladsch.treeIteration.util.looping-detailed"); - public static final Predicate