kramdown 1.17.0 → 2.0.0.beta1

data/doc/sidebar.template

@@ -1,22 +0,0 @@
-<h2>Support kramdown</h2>
-
-<p>If you like kramdown and would like to support it, you are welcome to make a small
-donation (Patreon or PayPal) -- it will surely be appreciated! Thanks!</p>
-
-<div style="text-align: center">
-
-<a href="https://www.patreon.com/bePatron?u=4908963" class="patreon">Become a Patron!</a>
-
-<form style="margin-top: 15px" action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
-<input type="hidden" name="cmd" value="_s-xclick">
-<input type="hidden" name="hosted_button_id" value="99HUWKWPMUHWG">
-<input type="image" src="//static.gettalong.org/images/paypal_small.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-</form>
-
-</div>
-
-<h2>Sponsors</h2>
-
-<p>GROSSWEBER provides <a href="http://grossweber.com/b/kramdown" target="_blank">software
-development consulting and training services</a>. <em>We like to work on open source. We use it heavily.
-We love kramdown!</em></p>

data/doc/sitemap.sitemap

@@ -1,5 +0,0 @@
----
-entries:
-  alcn: /**/*.html
-default_change_freq: monthly
----

data/doc/syntax.page

@@ -1,1799 +0,0 @@
----
-title: Syntax
-in_menu: true
-sort_info: 10
---- name:sidebar
-<div style="text-align: right">
-<a href="https://www.patreon.com/bePatron?u=4908963" class="patreon">Become a Patron!</a>
-</div>
-
-<h1>Contents</h1>
-
-{menu: {options: {descendants: true, levels: [2,6]}}}
---- name:content
-
-# kramdown Syntax
-
-This is version **<%= ::Kramdown::VERSION %>** of the syntax documentation.
-
-The kramdown syntax is based on the Markdown syntax and has been enhanced with features that are
-found in other Markdown implementations like [Maruku], [PHP Markdown Extra] and [Pandoc]. However,
-it strives to provide a strict syntax with definite rules and therefore isn't completely compatible
-with Markdown. Nonetheless, most Markdown documents should work fine when parsed with kramdown. All
-places where the kramdown syntax differs from the Markdown syntax are highlighted.
-
-Following is the complete syntax definition for all elements kramdown supports. Together with the
-documentation on the available converters, it is clearly specified what you will get when a kramdown
-document is converted.
-
-
-## Source Text Formatting
-
-A kramdown document may be in any encoding, for example ASCII, UTF-8 or ISO-8859-1, and the output
-will have the same encoding as the source.
-
-The document consists of two types of elements, block-level elements and span-level elements:
-
-* Block-level elements define the main structure of the content, for example, what part of the text
-  should be a paragraph, a list, a blockquote and so on.
-
-* Span-level elements mark up small text parts as, for example, emphasized text or a link.
-
-Thus span-level elements can only occur inside block-level elements or other span-level elements.
-
-You will often find references to the "first column" or "first character" of a line in a block-level
-element descriptions. Such a reference is always to be taken relative to the current indentation
-level because some block-level elements open up a new indentation level (e.g. blockquotes). The
-beginning of a kramdown document opens up the default indentation level which begins at the first
-column of the text.
-
-
-### Line Wrapping
-
-Some lightweight markup syntax don't work well in environments where lines are hard-wrapped. For
-example, this is the case with many email programs. Therefore kramdown allows content like
-paragraphs or blockquotes to be hard-wrapped, i.e. broken across lines. This is sometimes referred
-to as "lazy syntax" since the indentation or line prefix required for the first line of content is
-not required for the consecutive lines.
-
-Block-level elements that support line wrapping always end when one of the following conditions is
-met:
-
-* a [blank line](#blank-lines), an [EOB marker line](#eob-marker), a [block IAL](#block-ials) or the
-  end of the document (i.e. a [block boundary](#block-boundaries)),
-
-*  or an [HTML block](#html-blocks).
-
-Line wrapping is allowed throughout a kramdown document but there are some block-level elements that
-do *not* support being hard-wrapped:
-
-[headers](#headers)
-
-: This is not an issue in most situations since headers normally fit on one line. If a header text
-  gets too long for one line, you need to use HTML syntax instead.
-
-[fenced code blocks](#fenced-code-blocks)
-
-: The delimiting lines of a fenced code block do not support hard-wrapping. Since everything between
-  the delimiting lines is taken as is, the content of a fenced code block does also not support
-  hard-wrapping.
-
-[definition list terms](#definition-lists)
-
-: Each definition term has to appear on a separate line. Hard-wrapping would therefore introduce
-  additional definition terms. The definitions themselves, however, do support hard-wrapping.
-
-[tables](#tables)
-
-: Since each line of a kramdown table describes one table row or a separator, it is not possible to
-  hard-wrap tables.
-
-**Note** that it is **NOT** recommended to use lazy syntax to write a kramdown document. The
-flexibility that the kramdown syntax offers due to the issue of line wrapping hinders readability
-and should therefore not be used.
-
-
-### Usage of Tabs
-
-kramdown assumes that tab stops are set at multiples of four. This is especially important when
-using tabs for indentation in lists. Also, tabs may only be used at the beginning of a line when
-indenting text and must not be preceded by spaces. Otherwise the results may be unexpected.
-
-
-### Automatic and Manual Escaping
-
-Depending on the output format, there are often characters that need special treatment. For example,
-when converting a kramdown document to HTML one needs to take care of the characters `<`, `>` and
-`&`. To ease working with these special characters, they are automatically and correctly escaped
-depending on the output format.
-
-This means, for example, that you can just use `<`, `>` and `&` in a kramdown document and need not
-think about when to use their HTML entity counterparts. However, if you *do use* HTML entities or
-HTML tags which use one of the characters, the result will be correct nonetheless!
-
-Since kramdown also uses some characters to mark-up the text, there needs to be a way to escape
-these special characters so that they can have their normal meaning. This can be done by using
-backslash escapes. For example, you can use a literal back tick like this:
-
-    This \`is not a code\` span!
-
-Following is a list of all the characters (character sequences) that can be escaped:
-
-    \         backslash
-    .         period
-    *         asterisk
-    _         underscore
-    +         plus
-    -         minus
-    =         equal sign
-    `         back tick
-    ()[]{}<>  left and right parens/brackets/braces/angle brackets
-    #         hash
-    !         bang
-    <<        left guillemet
-    >>        right guillemet
-    :         colon
-    |         pipe
-    "         double quote
-    '         single quote
-    $         dollar sign
-
-
-## Block Boundaries
-
-Some block-level elements have to start and/or end on so called block boundaries, as stated in their
-documentation. There are two cases where block boundaries come into play:
-
-* If a block-level element has to start on a block boundary, it has to be preceded by either a
-  [blank line](#blank-lines), an [EOB marker](#eob-marker), a [block IAL](#block-ials) or it has to
-  be the first element.
-
-* If a block-level element has to end on a block boundary, it has to be followed by either a [blank
-  line](#blank-lines), an [EOB marker](#eob-marker), a [block IAL](#block-ials) or it has to be the
-  last element.
-
-
-
-# Structural Elements
-
-All structural elements are block-level elements and they are used to structure the content. They
-can mark up some text as, for example, a simple paragraph, a quote or as a list item.
-
-
-## Blank lines
-
-Any line that just contains white space characters such as spaces and tabs is considered a blank
-line by kramdown. One or more consecutive blank lines are handled as one empty blank line. Blank
-lines are used to separate block-level elements from each other and in this case they don't have
-semantic meaning. However, there are some cases where blank lines do have a semantic meaning:
-
-* When used in headers -- see the [headers section](#headers)
-* When used in code blocks -- see the [code blocks section](#code-blocks)
-* When used in lists -- see the [lists section](#lists)
-* When used in math blocks -- see the [math blocks section](#math-blocks)
-* When used for elements that have to start/end on [block boundaries](#block-boundaries)
-
-
-## Paragraphs
-
-Paragraphs are the most used block-level elements. One or more consecutive lines of text are
-interpreted as one paragraph. The first line of a paragraph may be indented up to three spaces, the
-other lines can have any amount of indentation because paragraphs support [line
-wrapping](#line-wrapping). In addition to the rules outlined in the section about line wrapping, a
-paragraph ends when a [definition list line](#definition-lists) is encountered.
-
-You can separate two consecutive paragraphs from each other by using one or more blank lines. Notice
-that a line break in the source does not mean a line break in the output (due to the [lazy
-syntax](#line-wrapping))!. If you want to have an explicit line break (i.e. a `<br />` tag) you need
-to end a line with two or more spaces or two backslashes! Note, however, that a line break on the
-last text line of a paragraph is not possible and will be ignored. Leading and trailing spaces will
-be stripped from the paragraph text.
-
-The following gives you an example of how paragraphs look like:
-
-    This para line starts at the first column. However,
-          the following lines can be indented any number of spaces/tabs.
-       The para continues here.
-
-      This is another paragraph, not connected to the above one. But  
-    with a hard line break. \\
-    And another one.
-{: .show-whitespaces .ws-lr}
-
-
-## Headers
-
-kramdown supports so called Setext style and atx style headers. Both forms can be used inside a
-single document.
-
-### Setext Style
-
-Setext style headers have to start on a [block boundary](#block-boundaries) with a line of text (the
-header text) and a line with only equal signs (for a first level header) or dashes (for a second
-level header). The header text may be indented up to three spaces but any leading or trailing spaces
-are stripped from the header text. The amount of equal signs or dashes is not significant, just one
-is enough but more may look better. The equal signs or dashes have to begin at the first column. For
-example:
-
-    First level header
-    ==================
-
-    Second level header
-    ------
-
-       Other first level header
-    =
-
-Since Setext headers start on block boundaries, this means in most situations that they have to be
-preceded by a blank line. However, blank lines are not necessary after a Setext header:
-
-    This is a normal
-    paragraph.
-
-    And A Header
-    ------------
-    And a paragraph
-
-    > This is a blockquote.
-
-    And A Header
-    ------------
-
-However, it is generally a good idea to also use a blank line after a Setext header because it looks
-more appropriate and eases reading of the document.
-
-> The original Markdown syntax allows one to omit the blank line before a Setext header. However,
-> this leads to ambiguities and makes reading the document harder than necessary. Therefore it is
-> not allowed in a kramdown document.
-{: .markdown-difference}
-
-An edge case worth mentioning is the following:
-
-    header
-    ---
-    para
-
-One might ask if this represents two paragraphs separated by a [horizontal rule](#horizontal-rules)
-or a second level header and a paragraph. As suggested by the wording in the example, the latter is
-the case. The general rule is that Setext headers are processed before horizontal rules.
-
-### atx Style
-
-atx style headers have to start on a [block boundary](#block-boundaries) with a line that contains
-one or more hash characters and then the header text. No spaces are allowed before the hash
-characters. The number of hash characters specifies the heading level: one hash character gives you
-a first level heading, two a second level heading and so on until the maximum of six hash characters
-for a sixth level heading. You may optionally use any number of hashes at the end of the line to
-close the header. Any leading or trailing spaces are stripped from the header text. For example:
-
-    # First level header
-
-    ### Third level header    ###
-
-    ## Second level header ######
-
-> Again, the original Markdown syntax allows one to omit the blank line before an atx style header.
-{: .markdown-difference}
-
-
-### Specifying a Header ID
-
-kramdown supports a nice way for explicitly setting the header ID which is taken from [PHP Markdown
-Extra] and [Maruku]: If you follow the header text with an opening curly bracket (separated from the
-text with a least one space), a hash, the ID and a closing curly bracket, the ID is set on the
-header. If you use the trailing hash feature of atx style headers, the header ID has to go after the
-trailing hashes. For example:
-
-    Hello        {#id}
-    -----
-
-    # Hello      {#id}
-
-    # Hello #    {#id}
-
-> This additional syntax is not part of standard Markdown.
-{: .markdown-difference}
-
-
-## Blockquotes
-
-A blockquote is started using the `>` marker followed by an optional space and the content of the
-blockquote. The marker itself may be indented up to three spaces. All following lines, whether they
-are started with the blockquote marker or just contain text, belong to the blockquote because
-blockquotes support [line wrapping](#line-wrapping).
-
-The contents of a blockquote are block-level elements. This means that if you are just using text as
-content that it will be wrapped in a paragraph. For example, the following gives you one blockquote
-with two paragraphs in it:
-
-    > This is a blockquote.
-    >     on multiple lines
-    that may be lazy.
-    >
-    > This is the second paragraph.
-
-Since the contents of a blockquote are block-level elements, you can nest blockquotes and use other
-block-level elements (this is also the reason why blockquotes need to support line wrapping):
-
-    > This is a paragraph.
-    >
-    > > A nested blockquote.
-    >
-    > ## Headers work
-    >
-    > * lists too
-    >
-    > and all other block-level elements
-
-Note that the first space character after the `>` marker does *not* count when counting spaces for
-the indentation of the block-level elements inside the blockquote! So [code blocks](#code-blocks)
-will have to be indented with five spaces or one space and one tab, like this:
-
-    > A code block:
-    >
-    >     ruby -e 'puts :works'
-
-[Line wrapping](#line-wrapping) allows one to be lazy but hinders readability and should therefore
-be avoided, especially with blockquotes. Here is an example of using blockquotes with line wrapping:
-
-    > This is a paragraph inside
-    a blockquote.
-    >
-    > > This is a nested paragraph
-    that continues here
-    > and here
-    > > and here
-
-
-## Code Blocks
-
-Code blocks can be used to represent verbatim text like markup, HTML or a program fragment because
-no syntax is parsed within a code block.
-
-### Standard Code Blocks
-
-A code block can be started by using four spaces or one tab and then the text of the code block. All
-following lines containing text, whether they adhere to this syntax or not, belong to the code block
-because code blocks support [line wrapping](#line-wrapping)). A wrapped code line is automatically
-appended to the preceding code line by substituting the line break with a space character. The
-indentation (four spaces or one tab) is stripped from each line of the code block.
-
-> The original Markdown syntax does not allow line wrapping in code blocks.
-{: .markdown-difference}
-
-Note that consecutive code blocks that are only separate by [blank lines](#blank-lines) are merged
-together into one code block:
-
-        Here comes some code
-
-        This text belongs to the same code block.
-
-If you want to have one code block directly after another one, you need to use an [EOB
-marker](#eob-marker) to separate the two:
-
-        Here comes some code
-    ^
-        This one is separate.
-
-### Fenced Code Blocks
-
-> This alternative syntax is not part of the original Markdown syntax. The idea and syntax comes
-> from the [PHP Markdown Extra] package.
-{: .markdown-difference}
-
-kramdown also supports an alternative syntax for code blocks which does not use indented blocks but
-delimiting lines. The starting line needs to begin with three or more tilde characters (`~`) and the
-closing line needs to have at least the number of tildes the starting line has. Everything between
-is taken literally as with the other syntax but there is no need for indenting the text. For
-example:
-
-    ~~~~~~~~
-    Here comes some code.
-    ~~~~~~~~
-
-If you need lines of tildes in such a code block, just start the code block with more tildes. For
-example:
-
-    ~~~~~~~~~~~~
-    ~~~~~~~
-    code with tildes
-    ~~~~~~~~
-    ~~~~~~~~~~~~~~~~~~
-
-This type of code block is especially useful for copy-pasted code since you don't need to indent the
-code.
-
-### Language of Code Blocks
-
-You can tell kramdown the language of a code block by using an [IAL](#inline-attribute-lists):
-
-    ~~~
-    def what?
-      42
-    end
-    ~~~
-    {: .language-ruby}
-
-The specially named class `language-ruby` tells kramdown that this code block is written in the Ruby
-language. Such information can be used, for example, by converters to do syntax highlighting on the
-code block.
-
-Fenced code blocks provide an easier way to specify the language, namely by appending the language
-of the code block to the end of the starting line:
-
-    ~~~ ruby
-    def what?
-      42
-    end
-    ~~~
-
-
-## Lists
-
-kramdown provides syntax elements for creating ordered and unordered lists as well as definition
-lists.
-
-### Ordered and Unordered lists
-
-Both ordered and unordered lists follow the same rules.
-
-A list is started with a list marker (in case of unordered lists one of `+`, `-` or `*` -- you can
-mix them -- and in case of ordered lists a number followed by a period) followed by one tab or at
-least one space, optionally followed by an [IAL](#inline-attribute-lists) that should be applied to
-the list item and then the first part of the content of the list item. The leading tabs or spaces
-are stripped away from this first line of content to allow for a nice alignment with the following
-content of a list item (see below). All following list items with the same marker type (unordered or
-ordered) are put into the same list. The numbers used for ordered lists are irrelevant, an ordered
-list always starts at 1.
-
-The following gives you an unordered list and an ordered list:
-
-    * kram
-    + down
-    - now
-
-    1. kram
-    2. down
-    3. now
-
-> The original Markdown syntax allows the markers of ordered and unordered lists to be mixed, the
-> first marker specifying the list type (ordered or unordered). This is not allowed in kramdown. As
-> stated, the above example will give you two lists (an unordered and an ordered) in kramdown and
-> only one unordered list in Markdown.
-{: .markdown-difference}
-
-The first list marker in a list may be indented up to three spaces. The column number of the first
-non-space character which appears after the list item marker on the same line specifies the
-indentation that has to be used for the following lines of content of the list item. If there is no
-such character, the indentation that needs to be used is four spaces or one tab. Indented lines may
-be followed by lines containing text with any amount of indentation due to [line
-wrapping](#line-wrapping). Note, however, that in addition to the rules outlined in the section
-about line wrapping, a list item also ends when a line with another list item marker is encountered
--- see the next paragraph.
-
-The indentation is stripped from the content and the content (note that the content naturally also
-contains the content of the line with the item marker) is processed as text containing block-level
-elements. All other list markers in the list may be indented up to three spaces or the number of
-spaces used for the indentation of the last list item minus one, whichever number is smaller. For
-example:
-
-    * This is the first line. Since the first non-space characters appears in
-      column 3, all other indented lines have to be indented 2 spaces.
-    However, one could be lazy and not indent a line but this is not
-    recommended.
-    *       This is the another item of the list. It uses a different number
-       of spaces for indentation which is okay but should generally be avoided.
-       * The list item marker is indented 3 spaces which is allowed but should
-         also be avoided and starts the third list item. Note that the lazy
-         line in the second list item may make you believe that this is a
-         sub-list which it isn't! So avoid being lazy!
-
-So, while the above is possible and creates one list with three items, it is not advised to use
-different (marker and list content) indents for same level list items as well as lazy indentation!
-It is much better to write such a list in the following way:
-
-    * This is the first list item bla blabla blabla blabla blabla blabla
-      blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla
-      blabla blabla blabla bla
-    * This is the another item of the list. bla blabla blabla blabla blabla
-      blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla
-
-> The original Markdown syntax also allows you to indent the marker, however, the behaviour of what
-> happens with the list items is not clearly specified and may surprise you.
->
-> Also, Markdown uses a fixed number of spaces/tabs to indent the lines that belong to a list item!
-{: .markdown-difference}
-
-Unordered and ordered lists work the same way in regard to the indentation:
-
-    * list 1 item 1
-     * list 1 item 2 (indent 1 space)
-      * list 1 item 3 (indent 2 spaces)
-       * list 1 item 4  (indent 3 spaces)
-        * lazy text belonging to above item 4
-
-^
-
-    1. list 1 item 1
-     2. list 1 item 2 (indent 1 space)
-      3. list 1 item 3 (indent 2 spaces)
-       4. list 1 item 4  (indent 3 spaces)
-        5. lazy text belonging to above item 4
-
-^
-
-    * list 1 item 1
-      * nested list item 1
-      * nested list item 2
-    * list 1 item 2
-      * nested list item 1
-
-^
-
-    1. list 1 item 1
-       1. nested list item 1
-       2. nested list item 2
-    10. list 1 item 2
-        1. nested list item 1
-
-^
-
-    1. text for this list item
-       further text (indent 3 spaces)
-
-    10. text for this list item
-        further text (indent 4 spaces)
-
-When using tabs for indenting the content of a list item, remember that tab stops occur at multiples
-of four for kramdown. Tabs are correctly converted to spaces for calculating the indentation. For
-example:
-
-    *   Using a tab to indent this line, the tab only counts as three spaces
-        and therefore the overall indentation is four spaces.
-
-       1.   The tab after the marker counts here as three spaces. Since the
-            indentation of the marker is three spaces and the marker itself
-            takes two characters, the overall indentation needed for the
-            following lines is eight spaces or two tabs.
-
-It is clear that you might get unexpected results if you mix tabs and spaces or if you don't have
-the tab stops set to multiples of four in your editor! Therefore this should be avoided!
-
-The content of a list item is made up of either text or block-level elements. Simple list items only
-contain text like in the above examples. They are not even wrapped in a paragraph tag. If the first
-list text is followed by one or more blank lines, it will be wrapped in a paragraph tag:
-
-    * kram
-
-    * down
-    * now
-
-In the above example, the first list item text will be wrapped in a paragraph tag since it is
-followed by a blank line whereas the second list item contains just text. There is obviously a
-problem for doing this with the last list item when it contains only text. You can circumvent this
-by leaving a blank line after the last list item and using an EOB marker:
-
-    * Not wrapped in a paragraph
-    * Wrapped in a paragraph due to the following blank line.
-
-    * Also wrapped in a paragraph due to the
-      following blank line and the EOB marker.
-
-    ^
-
-The text of the last list item is also wrapped in a paragraph tag if *all* other list items contain
-a proper paragraph as first element. This makes the following use case work like expected, i.e.
-*all* the list items are wrapped in paragraphs:
-
-    * First list item
-
-    * Second list item
-
-    * Last list item
-
-> The original Markdown syntax page specifies that list items which are separated by one or more
-> blank lines are wrapped in paragraph tags. This means that the first text will also be wrapped in
-> a paragraph if you have block-level elements in a list which are separated by blank lines. The
-> above rule is easy to remember and lets you exactly specify when the first list text should be
-> wrapped in a paragraph. The idea for the above rule comes from the [Pandoc] package.
-{: .markdown-difference}
-
-As seen in the examples above, blank lines between list items are allowed.
-
-Since the content of a list item can contain block-level elements, you can do the following:
-
-    *   First item
-
-        A second paragraph
-
-        * nested list
-
-        > blockquote
-
-    *   Second item
-
-However, there is a problem when you want to have a code block immediately after a list item. You
-can use an EOB marker to circumvent this problem:
-
-    *   This is a list item.
-
-        The second para of the list item.
-    ^
-        A code block following the list item.
-
-You can have any block-level element as first element in a list item. However, as described above,
-the leading tabs or spaces of the line with the list item marker are stripped away. This leads to a
-problem when you want to have a code block as first element. The solution to this problem is the
-following construct:
-
-    * 
-            This is a code block (indentation needs to be 4(1)+4(1)
-            spaces (tabs)).
-{: .show-whitespaces .ws-lr}
-
-Note that the list marker needs to be followed with at least one space or tab! Otherwise the line is
-not recognized as the start of a list item but interpreted as a paragraph containing the list
-marker.
-
-If you want to have one list directly after another one (both with the same list type, i.e. ordered
-or unordered), you need to use an EOB marker to separate the two:
-
-    * List one
-    ^
-    * List two
-
-Since paragraphs support [line wrapping](#line-wrapping), it would usually not be possible to create
-compact nested list, i.e. a list where the text is not wrapped in paragraphs because there is no
-blank line but a sub list after it:
-
-    *   This is just text.
-        * this is a sub list item
-          * this is a sub sub list item
-    * This is just text,
-        spanning two lines
-      * this is a nested list item.
-
-However, this is an often used syntax and is therefore support by kramdown.
-
-If you want to start a paragraph with something that looks like a list item marker, you need to
-escape it. This is done by escaping the period in an ordered list or the list item marker in an
-unordered list:
-
-    1984\. It was great
-    \- others say that, too!
-
-As mentioned at the beginning, an optional IAL for applying attributes to a list item can be used
-after the list item marker:
-
-    * {:.cls} This item has the class "cls".
-      Here continues the above paragraph.
-
-    * This is a normal list item.
-
-
-### Definition Lists
-
-> This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
-> the [PHP Markdown Extra] package.
-{: .markdown-difference}
-
-Definition lists allow you to assign one or more definitions to one or more terms.
-
-A definition list is started when a normal paragraph is followed by a line with a definition marker
-(a colon which may be optionally indented up to three spaces), then at least one tab or one space,
-optionally followed by an [IAL](#inline-attribute-lists) that should be applied to the list item and
-then the first part of the definition. The line with the definition marker may optionally be
-separated from the preceding paragraph by a blank line. The leading tabs or spaces are stripped away
-from this first line of the definition to allow for a nice alignment with the following definition
-content. Each line of the preceding paragraph is taken to be a term and the lines separately parsed
-as span-level elements. Each such term may optionally start with an [IAL](#inline-attribute-lists)
-that should be applied to the term.
-
-The following is a simple definition list:
-
-    kramdown
-    : A Markdown-superset converter
-
-    Maruku
-    :     Another Markdown-superset converter
-
-The column number of the first non-space character which appears after a definition marker on the
-same line specifies the indentation that has to be used for the following lines of the definition.
-If there is no such character, the indentation that needs to be used is four spaces or one tab.
-Indented lines may be followed by lines containing text with any amount of indentation due to [line
-wrapping](#line-wrapping). Note, however, that in addition to the rules outlined in the section
-about line wrapping, a list item also ends when a line with another definition marker is encountered.
-
-The indentation is stripped from the definition and it (note that the definition naturally also
-contains the content of the line with the definition marker) is processed as text containing block
-level elements. If there is more than one definition, all other definition markers for the term may
-be indented up to three spaces or the number of spaces used for the indentation of the last
-definition minus one, whichever number is smaller. For example:
-
-    definition term 1
-    definition term 2
-    : This is the first line. Since the first non-space characters appears in
-    column 3, all other lines have to be indented 2 spaces (or lazy syntax may
-      be used after an indented line). This tells kramdown that the lines
-      belong to the definition.
-    :       This is the another definition for the same term. It uses a
-            different number of spaces for indentation which is okay but
-            should generally be avoided.
-       : The definition marker is indented 3 spaces which is allowed but
-         should also be avoided.
-
-So, while the above is possible and creates a definition list with two terms and three definitions
-for them, it is not advised to use different (definition marker and definition) indents in the same
-definition list as well as lazy indentation!
-
-The definition for a term is made up of text and/or block-level elements. If a definition is *not*
-preceded by a blank line, the first part of the definition will just be text if it would be a
-paragraph otherwise:
-
-    definition term
-    : This definition will just be text because it would normally be a
-      paragraph and the there is no preceding blank line.
-
-      > although the definition contains other block-level elements
-
-    : This definition *will* be a paragraph since it is preceded by a
-      blank line.
-
-The rules about having any block-level element as first element in a list item also apply to a
-definition.
-
-As mentioned at the beginning, an optional IAL for applying attributes to a term or a definition can
-be used:
-
-    {:#term} Term with id="term"
-    : {:.cls} Definition with class "cls"
-
-    {:#term1} First term
-    {:#term2} Second term
-    : {:.cls} Definition
-
-
-## Tables
-
-> This syntax feature is not part of the original Markdown syntax. The syntax is based on the one
-> from the [PHP Markdown Extra] package.
-{: .markdown-difference}
-
-Sometimes one wants to include simple tabular data in a kramdown document for which using a
-full-blown HTML table is just too much. kramdown supports this with a simple syntax for ASCII
-tables.
-
-Tables can be created with or without a leading pipe character: If the first line of a table
-contains a pipe character at the start of the line (optionally indented up to three spaces), then
-all leading pipe characters (i.e. pipe characters that are only preceded by whitespace) are ignored
-on all table lines. Otherwise they are not ignored and count when dividing a table line into table
-cells.
-
-There are four different line types that can be used in a table:
-
-* *Table rows* define the content of a table.
-
-  A table row is any line that contains at least one pipe character and is not identified as any
-  other type of table line! The table row is divided into individual table cells by pipe characters.
-  An optional trailing pipe character is ignored. Note that literal pipe characters need to be
-  escaped *except* if they occur in code spans or HTML `<code>` elements!
-
-  Header rows, footer rows and normal rows are all done using these table rows. Table cells can only
-  contain a single line of text, no multi-line text is supported. The text of a table cell is parsed
-  as span-level elements.
-
-  Here are some example table rows:
-
-      | First cell|Second cell|Third cell
-      | First | Second | Third |
-
-      First | Second | | Fourth |
-
-* *Separator lines* are used to split the table body into multiple body parts.
-
-  A separator line is any line that contains only pipes, dashes, pluses, colons and spaces/tabs and
-  which contains at least one dash and one pipe character. The pipe and plus characters can be used
-  to visually separate columns although this is not needed. Multiple separator lines after another
-  are treated as one separator line.
-
-  Here are some example separator lines:
-
-      |----+----|
-      +----|----+
-      |---------|
-      |-
-      | :-----: |
-      -|-
-
-* The first separator line after at least one table row is treated specially, namely as *header
-  separator line*. It is used to demarcate header rows from normal table rows and/or to set column
-  alignments. All table rows above the header separator line are considered to be header rows.
-
-  The header separator line can be specially formatted to contain column alignment definitions: An
-  alignment definition consists of an optional space/tab followed by an optional colon, one or more
-  dashes, an optional colon and another optional space/tab. The colons of an alignment definition
-  are used to set the alignment of a column: if there are no colons, the column uses the default
-  alignment, if there is a colon only before the dashes, the column is left aligned, if there are
-  colons before and after the dashes, the column is center aligned and if there is only a colon
-  after the dashes, the column is right aligned. Each alignment definition sets the alignment for
-  one column, the first alignment definition for the first column, the second alignment definition
-  for the second column and so on.
-
-  Here are some example header separator lines with alignment definitions:
-
-      |---+---+---|
-      + :-: |:------| ---:|
-      | :-: :- -: -
-      :-: | :-
-
-* A *footer separator line* is used to demarcate footer rows from normal table rows. All table rows
-  below the footer separator line are considered to be footer rows.
-
-  A footer separator line is like a normal separator line except that dashes are replaced by equal
-  signs. A footer separator line may only appear once in a table. If multiple footer separator lines
-  are used in one table, only the last is treated as footer separator line, all others are treated
-  as normal separator lines. Normal separator lines that are used after the footer separator line
-  are ignored.
-
-  Here are some example footer separator lines:
-
-      |====+====|
-      +====|====+
-      |=========|
-      |=
-
-Trailing spaces or tabs are ignored in all cases. To simplify table creation and maintenance,
-header, footer and normal separator lines need not specify the same number of columns as table rows;
-even `|-` and `|=` are a valid separators.
-
-Given the above components, a table is specified by
-
-* an optional separator line,
-* optionally followed by zero, one or more table rows followed by a header separator line,
-* one or more table rows, optionally interspersed with separator lines,
-* optionally followed by a footer separator line and zero, one or more table rows and
-* an optional trailing separator line.
-
-Also note
-
-* that the first line of a table must not have more than three spaces of indentation before the
-  first non-space character,
-* that each line of a table needs to have at least one not escaped pipe character so that kramdown
-  recognizes it as a line belonging to the table and
-* that tables have to start and end on [block boundaries](#block-boundaries)!
-
-> The table syntax differs from the one used in [PHP Markdown Extra] as follows:
->
-> * kramdown tables do not need to have a table header.
-> * kramdown tables can be structured using separator lines.
-> * kramdown tables can contain a table footer.
-> * kramdown tables need to be separated from other block-level elements.
-{: .markdown-difference}
-
-Here is an example for a kramdown table with a table header row, two table bodies and a table footer
-row:
-
-    |-----------------+------------+-----------------+----------------|
-    | Default aligned |Left aligned| Center aligned  | Right aligned  |
-    |-----------------|:-----------|:---------------:|---------------:|
-    | First body part |Second cell | Third cell      | fourth cell    |
-    | Second line     |foo         | **strong**      | baz            |
-    | Third line      |quux        | baz             | bar            |
-    |-----------------+------------+-----------------+----------------|
-    | Second body     |            |                 |                |
-    | 2 line          |            |                 |                |
-    |=================+============+=================+================|
-    | Footer row      |            |                 |                |
-    |-----------------+------------+-----------------+----------------|
-
-The above example table is rather time-consuming to create without the help of an ASCII table
-editor. However, the table syntax is flexible and the above table could also be written like this:
-
-    |---
-    | Default aligned | Left aligned | Center aligned | Right aligned
-    |-|:-|:-:|-:
-    | First body part | Second cell | Third cell | fourth cell
-    | Second line |foo | **strong** | baz
-    | Third line |quux | baz | bar
-    |---
-    | Second body
-    | 2 line
-    |===
-    | Footer row
-
-
-## Horizontal Rules
-
-A horizontal rule for visually separating content is created by using three or more asterisks,
-dashes or underscores (these may not be mixed on a line), optionally separated by spaces or tabs, on
-an otherwise blank line. The first asterisk, dash or underscore may optionally be indented up to
-three spaces. The following examples show different possibilities to create a horizontal rule:
-
-    * * *
-
-    ---
-
-      _  _  _  _
-
-    ---------------
-
-
-## Math Blocks
-
-> This syntax feature is not part of the original Markdown syntax. The idea comes from the [Maruku]
-> and [Pandoc] packages.
-{: .markdown-difference}
-
-kramdown has built-in support for block and span-level mathematics written in LaTeX.
-
-A math block needs to start and end on [block boundaries](#block-boundaries). It is started using
-two dollar signs, optionally indented up to three spaces. The math block continues until the next
-two dollar signs (which may be on the same line or on one of the next lines) that appear at the end
-of a line, i.e. they may only be followed by whitespace characters. The content of a math block has
-to be valid LaTeX math. It is always wrapped inside a `\begin{displaymath}...\end{displaymath}`
-enviroment except if it begins with a `\begin` statement.
-
-The following kramdown fragment
-
-    $$
-    \begin{align*}
-      & \phi(x,y) = \phi \left(\sum_{i=1}^n x_ie_i, \sum_{j=1}^n y_je_j \right)
-      = \sum_{i=1}^n \sum_{j=1}^n x_i y_j \phi(e_i, e_j) = \\
-      & (x_1, \ldots, x_n) \left( \begin{array}{ccc}
-          \phi(e_1, e_1) & \cdots & \phi(e_1, e_n) \\
-          \vdots & \ddots & \vdots \\
-          \phi(e_n, e_1) & \cdots & \phi(e_n, e_n)
-        \end{array} \right)
-      \left( \begin{array}{c}
-          y_1 \\
-          \vdots \\
-          y_n
-        \end{array} \right)
-    \end{align*}
-    $$
-
-renders (using Javascript library [MathJax](http://www.mathjax.org/)) as
-
-$$
-\begin{align*}
-  & \phi(x,y) = \phi \left(\sum_{i=1}^n x_ie_i, \sum_{j=1}^n y_je_j \right)
-  = \sum_{i=1}^n \sum_{j=1}^n x_i y_j \phi(e_i, e_j) = \\
-  & (x_1, \ldots, x_n) \left( \begin{array}{ccc}
-      \phi(e_1, e_1) & \cdots & \phi(e_1, e_n) \\
-      \vdots & \ddots & \vdots \\
-      \phi(e_n, e_1) & \cdots & \phi(e_n, e_n)
-    \end{array} \right)
-  \left( \begin{array}{c}
-      y_1 \\
-      \vdots \\
-      y_n
-    \end{array} \right)
-\end{align*}
-$$
-
-Using inline math is also easy: just surround your math content with two dollar signs, like with a
-math block. If you don't want to start an inline math statement, just escape the dollar signs and
-they will be treated as simple dollar signs.
-
-> **Note** that LaTeX code that uses the pipe symbol `|` in inline math statements may lead to a
-> line being recognized as a table line. This problem can be avoided by using the `\vert` command
-> instead of `|`!
-{:.information}
-
-If you have a paragraph that looks like a math block but should actually be a paragraph with just an
-inline math statement, you need to escape the first dollar sign:
-
-    The following is a math block:
-
-    $$ 5 + 5 $$
-
-    But next comes a paragraph with an inline math statement:
-
-    \$$ 5 + 5 $$
-
-If you don't even want the inline math statement, escape the first two dollar signs:
-
-    \$\$ 5 + 5 $$
-
-## HTML Blocks
-
-> The original Markdown syntax specifies that an HTML block must start at the left margin, i.e. no
-> indentation is allowed. Also, the HTML block has to be surrounded by blank lines. Both
-> restrictions are lifted for kramdown documents. Additionally, the original syntax does not allow
-> you to use Markdown syntax in HTML blocks which is allowed with kramdown.
-{: .markdown-difference}
-
-An HTML block is potentially started if a line is encountered that begins with a non-span-level HTML
-tag or a general XML tag (opening or closing) which may be indented up to three spaces.
-
-The following HTML tags count as span-level HTML tags and *won't* start an HTML block if found at
-the beginning of an HTML block line:
-
-    a abbr acronym b big bdo br button cite code del dfn em i img input
-    ins kbd label option q rb rbc rp rt rtc ruby samp select small span
-    strong sub sup textarea tt var
-
-Further parsing of a found start tag depends on the tag and in which of three possible ways its
-content is parsed:
-
-* Parse as raw HTML block: If the HTML/XML tag content should be handled as raw HTML, then only
-  HTML/XML tags are parsed from this point onwards and text is handled as raw, unparsed text until
-  the matching end tag is found or until the end of the document. Each found tag will be parsed as
-  raw HTML again. However, if a tag has a `markdown` attribute, this attribute controls parsing of
-  this one tag (see below).
-
-  Note that the parser basically supports only correct XHTML! However, there are some exceptions.
-  For example, attributes without values (i.e. boolean attributes) are also supported and elements
-  without content like `<hr />` can be written as `<hr>`. If an invalid closing tag is found, it is
-  ignored.
-
-* Parse as block-level elements: If the HTML/XML tag content should be parsed as text containing
-  block-level elements, the remaining text on the line will be parsed by the block-level parser as
-  if it appears on a separate line (**Caution**: This also means that if the line consists of the
-  start tag, text and the end tag, the end tag will not be found!). All following lines are parsed
-  as block-level elements until an HTML block line with the matching end tag is found or until the
-  end of the document.
-
-* Parse as span-level elements: If the HTML/XML tag content should be parsed as text containing span
-  level elements, then all text until the *next* matching end tag or until the end of the document
-  will be the content of the tag and will later be parsed by the span-level parser. This also means
-  that if the matching end tag is inside what appears to be a code span, it is still used!
-
-If there is text after an end tag, it will be parsed as if it appears on a separate line except when
-inside a raw HTML block.
-
-Also, if an invalid closing tag is found, it is ignored.
-
-Note that all HTML tag and attribute names are converted to lowercase!
-
-By default, kramdown parses all block HTML tags and all XML tags as raw HTML blocks. However, this
-can be configured with the `parse_block_html`. If this is set to `true`, then syntax parsing in HTML
-blocks is globally enabled. It is also possible to enable/disable syntax parsing on a tag per tag
-basis using the `markdown` attribute:
-
-* If an HTML tag has an attribute `markdown="0"`, then the tag is parsed as raw HTML block.
-
-* If an HTML tag has an attribute `markdown="1"`, then the default mechanism for parsing syntax in
-  this tag is used.
-
-* If an HTML tag has an attribute `markdown="block"`, then the content of the tag is parsed as block
-  level elements.
-
-* If an HTML tag has an attribute `markdown="span"`, then the content of the tag is parsed as span
-  level elements.
-
-The following list shows which HTML tags are parsed in which mode by default when `markdown="1"` is
-applied or `parse_block_html` is `true`:
-
-Parse as raw HTML
-: 
-        script style math option textarea pre code kbd samp var
-
-    Also, all general XML tags are parsed as raw HTML blocks.
-
-Parse as block-level elements
-: 
-        applet button blockquote body colgroup dd div dl fieldset form iframe li
-        map noscript object ol table tbody thead tfoot tr td ul
-
-Parse as span-level elements
-: 
-        a abbr acronym address b bdo big cite caption code del dfn dt em
-        h1 h2 h3 h4 h5 h6 i ins kbd label legend optgroup p pre q rb rbc
-        rp rt rtc ruby samp select small span strong sub sup th tt var
-
-> Remember that all span-level HTML tags like `a` or `b` do not start a HTML block! However, the
-> above lists also include span-level HTML tags in the case the `markdown` attribute is used on a
-> tag inside a raw HTML block.
-
-Here is a simple example input and its HTML output with `parse_block_html` set to `false`:
-
-    This is a para.
-    <div>
-    Something in here.
-    </div>
-    Other para.
-^
-    <p>This is a para.</p>
-    <div>
-    Something in here.
-    </div>
-    <p>Other para.</p>
-
-As one can see the content of the `div` tag will be parsed as raw HTML block and left alone.
-However, if the `markdown="1"` attribute was used on the `div` tag, the content would be parsed as
-block-level elements and therefore converted to a paragraph.
-
-You can also use several HTML tags at once:
-
-    <div id="content"><div id="layers"><div id="layer1">
-    This is some text in the `layer1` div.
-    </div>
-    This is some text in the `layers` div.
-    </div></div>
-    This is a para outside the HTML block.
-
-However, remember that if the content of a tag is parsed as block-level elements, the content that
-appears after a start/end tag but on the same line, is processed as if it appears on a new line:
-
-    <div markdown="1">This is the first part of a para,
-    which is continued here.
-    </div>
-
-    <p markdown="1">This works without problems because it is parsed as
-    span-level elements</p>
-
-    <div markdown="1">The end tag is not found because
-    this line is parsed as a paragraph</div>
-
-Since setting `parse_block_html` to `true` can lead to some not wanted behaviour, it is generally
-better to selectively enable or disable block/span-level elements parsing by using the `markdown`
-attribute!
-
-Unclosed block-level HTML tags are correctly closed at the end of the document to ensure correct
-nesting and invalidly used end tags are removed from the output:
-
-    This is a para.
-    <div markdown="1">
-    Another para.
-    </p>
-^
-    <p>This is a para.</p>
-    <div>
-      <p>Another para.</p>
-    </div>
-
-The parsing of processing instructions and XML comments is also supported. The content of both, PIs
-and XML comments, may span multiple lines. The start of a PI/XML comment may only appear at the
-beginning of a line, optionally indented up to three spaces. If there is text after the end of a PI
-or XML comment, it will be parsed as if it appears on a separate line. kramdown syntax in PIs/XML
-comments is not processed:
-
-    This is a para.
-    <!-- a *comment* -->
-    <? a processing `instruction`
-       spanning multiple lines
-    ?> First part of para,
-    continues here.
-
-
-
-# Text Markup
-
-These elements are all span-level elements and used inside block-level elements to markup text
-fragments. For example, one can easily create links or apply emphasis to certain text parts.
-
-Note that empty span-level elements are not converted to empty HTML tags but are copied as-is to the
-output.
-
-
-
-## Links and Images
-
-Three types of links are supported: automatic links, inline links and reference links.
-
-### Automatic Links
-
-This is the easiest one to create: Just surround a web address or an email address with angle
-brackets and the address will be turned into a proper link. The address will be used as link target
-and as link text. For example:
-
-    Information can be found on the <http://example.com> homepage.
-    You can also mail me: <me.example@example.com>
-
-It is not possible to specify a different link text using automatic links -- use the other link
-types for this!
-
-
-### Inline Links
-
-As the wording suggests, inline links provide all information inline in the text flow. Reference
-style links only provide the link text in the text flow and everything else is defined
-elsewhere. This also allows you to reuse link definitions.
-
-An inline style link can be created by surrounding the link text with square brackets, followed
-immediately by the link URL (and an optional title in single or double quotes preceded by at least
-one space) in normal parentheses. For example:
-
-    This is [a link](http://rubyforge.org) to a page.
-    A [link](../test "local URI") can also have a title.
-    And [spaces](link with spaces.html)!
-
-Notes:
-
-* The link text is treated like normal span-level text and therefore is parsed and converted.
-  However, if you use square brackets within the link text, you have to either properly nest them or
-  to escape them. It is not possible to create nested links!
-
-  The link text may also be omitted, e.g. for creating link anchors.
-
-* The link URL has to contain properly nested parentheses if no title is specified, or the link URL
-  must be contained in angle brackets (incorrectly nested parentheses are allowed).
-
-* The link title may not contain its delimiters and may not be empty.
-
-* Additional link attributes can be added by using a [span IAL](#span-ials) after the inline link,
-  for example:
-
-      This is a [link](http://example.com){:hreflang="de"}
-
-### Reference Links
-
-To create a reference style link, you need to surround the link text with square brackets (as with
-inline links), followed by optional spaces/tabs/line breaks and then optionally followed with
-another set of square brackets with the link identifier in them. A link identifier may not contain a
-closing bracket and, when specified in a link definition, newline characters; it is also not case
-sensitive, line breaks and tabs are converted to spaces and multiple spaces are compressed into one.
-For example:
-
-    This is a [reference style link][linkid] to a page. And [this]
-    [linkid] is also a link. As is [this][] and [THIS].
-
-If you don't specify a link identifier (i.e. only use empty square brackets) or completely omit the
-second pair of square brackets, the link text is converted to a valid link identifier by removing
-all invalid characters and inserting spaces for line breaks. If there is a link definition found for
-the link identifier, a link will be created. Otherwise the text is not converted to a link.
-
-As with inline links, additional link attributes can be added by using a [span IAL](#span-ials)
-after the reference link.
-
-### Link Definitions
-
-The link definition can be put anywhere in the document. It does not appear in the output. A link
-definition looks like this:
-
-    [linkid]: http://www.example.com/ "Optional Title"
-
-> Link definitions are, despite being described here, non-content block-level elements.
-{: .information}
-
-The link definition has the following structure:
-
-* The link identifier in square brackets, optionally indented up to three spaces,
-* then a colon and one or more optional spaces/tabs,
-* then the link URL which must contain at least one non-space character, or a left angle bracket,
-  the link URL and a right angle bracket,
-* then optionally the title in single or double quotes, separated from the link URL by one or more
-  spaces or on the next line by itself indented any number of spaces/tabs.
-
-> The original Markdown syntax also allowed the title to be specified in parenthesis. This is not
-> allowed for consistency with the inline title.
-{: .markdown-difference}
-
-If you have some text that looks like a link definition but should really be a link and some text,
-you can escape the colon after the link identifier:
-
-    The next paragraph contains a link and some text.
-
-    [Room 100]\: There you should find everything you need!
-
-    [Room 100]: link_to_room_100.html
-
-Although link definitions are non-content block-level elements, [block IALs](#block-ials) can be
-used on them to specify additional attributes for the links:
-
-    [linkid]: http://example.com
-    {:hreflang="de"}
-
-### Images
-
-Images can be specified via a syntax that is similar to the one used by links. The difference is
-that you have to use an exclamation mark before the first square bracket and that the link text of a
-normal link becomes the alternative text of the image link. As with normal links, image links can be
-written inline or reference style. For example:
-
-    Here comes a ![smiley](../images/smiley.png)! And here
-    ![too](../images/other.png 'Title text'). Or ![here].
-    With empty alt text ![](see.jpg)
-
-The link definition for images is exactly the same as the link definition for normal links. Since
-additional attributes can be added via span and block IALs, it is possible, for example, to specify
-image width and height:
-
-    Here is an inline ![smiley](smiley.png){:height="36px" width="36px"}.
-
-    And here is a referenced ![smile]
-
-    [smile]: smile.png
-    {: height="36px" width="36px"}
-
-## Emphasis
-
-kramdown supports two types of emphasis: light and strong emphasis. Text parts that are surrounded
-with single asterisks `*` or underscores `_` are treated as text with light emphasis, text parts
-surrounded with two asterisks or underscores are treated as text with strong emphasis. Surrounded
-means that the starting delimiter must not be followed by a space and that the stopping delimiter
-must not be preceded by a space.
-
-Here is an example for text with light and strong emphasis:
-
-    *some text*
-    _some text_
-    **some text**
-    __some text__
-
-The asterisk form is also allowed within a single word:
-
-    This is un*believe*able! This d_oe_s not work!
-
-Text can be marked up with both light and strong emphasis, possibly using different delimiters.
-However, it is not possible to nest strong within strong or light within light emphasized text:
-
-    This is a ***text with light and strong emphasis***.
-    This **is _emphasized_ as well**.
-    This *does _not_ work*.
-    This **does __not__ work either**.
-
-If one or two asterisks or underscores are surrounded by spaces, they are treated literally. If you
-want to force the literal meaning of an asterisk or an underscore you can backslash-escape it:
-
-    This is a * literal asterisk.
-    These are ** two literal asterisk.
-    As \*are\* these!
-
-
-## Code Spans
-
-This is the span-level equivalent of the [code block](#code-blocks) element. You can markup a text
-part as code span by surrounding it with backticks `` ` ``. For example:
-
-    Use `<html>` tags for this.
-
-Note that all special characters in a code span are treated correctly. For example, when a code span
-is converted to HTML, the characters `<`, `>` and `&` are substituted by their respective HTML
-counterparts.
-
-To include a literal backtick in a code span, you need to use two or more backticks as delimiters.
-You can insert one optional space after the starting and before the ending delimiter (these spaces
-are not used in the output). For example:
-
-    Here is a literal `` ` `` backtick.
-    And here is ``  `some`  `` text (note the two spaces so that one is left
-    in the output!).
-
-A single backtick surrounded by spaces is treated as literal backtick. If you want to force the
-literal meaning of a backtick you can backslash-escape it:
-
-    This is a ` literal backtick.
-    As \`are\` these!
-
-As with [code blocks](#language-of-code-blocks) you can set the language of a code span by using an
-[IAL](#inline-attribute-lists):
-
-    This is a Ruby code fragment `x = Class.new`{:.language-ruby}
-
-
-## HTML Spans
-
-HTML tags cannot only be used on the block-level but also on the span-level. Span-level HTML tags
-can only be used inside one block-level element, it is not possible to use a start tag in one block
-level element and the end tag in another. Note that only correct XHTML is supported! This means that
-you have to use, for example, `<br />` instead of `<br>` (although kramdown tries to fix such errors
-if possible).
-
-By default, kramdown parses kramdown syntax inside span HTML tags. However, this behaviour can be
-configured with the `parse_span_html` option. If this is set to `true`, then syntax parsing in HTML
-spans is enabled, if it is set to `false`, parsing is disabled. It is also possible to
-enable/disable syntax parsing on a tag per tag basis using the `markdown` attribute:
-
-* If an HTML tag has an attribute `markdown="0"`, then no parsing (except parsing of HTML span tags)
-  is done inside that HTML tag.
-
-* If an HTML tag has an attribute `markdown="1"`, then the content of the tag is parsed as span
-  level elements.
-
-* If an HTML tag has an attribute `markdown="block"`, then a warning is issued because HTML spans
-  cannot contain block-level elements and the attribute is ignored.
-
-* If an HTML tag has an attribute `markdown="span"`, then the content of the tag is parsed as span
-  level elements.
-
-The content of a span-level HTML tag is normally parsed as span-level elements. Note, however, that
-some tags like `<script>` are not parsed, i.e. their content is not modified.
-
-Processing instructions and XML comments can also be used (their content is not parsed). However, as
-with HTML tags the start and the end have to appear in the same block-level element.
-
-Span-level PIs and span-level XML comments as well as general span-level HTML and XML tags have to
-be preceded by at least one non whitespace character on the same line so that kramdown correctly
-recognizes them as span-level element and not as block-level element. However, all span HTML tags,
-i.e. `a`, `em`, `b`, ..., (opening or closing) can appear at the start of a line.
-
-Unclosed span-level HTML tags are correctly closed at the end of the span-level text to ensure
-correct nesting and invalidly used end tags or block HTML tags are removed from the output:
-
-    This is </invalid>.
-
-    This <span>is automatically closed.
-^
-    <p>This is .</p>
-
-    <p>This <span>is automatically closed.</span></p>
-
-Also note that one or more consecutive new line characters in an HTML span tag are replaced by a
-single space, for example:
-
-    Link: <a href="some
-    link">text</a>
-^
-    <p>Link: <a href="some link">text</a></p>
-
-
-## Footnotes
-
-> This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
-> the [PHP Markdown Extra] package.
-{: .markdown-difference}
-
-Footnotes in kramdown are similar to reference style links and link definitions. You need to place
-the footnote marker in the correct position in the text and the actual footnote content can be
-defined anywhere in the document.
-
-More exactly, a footnote marker can be created by placing the footnote name in square brackets.
-The footnote name has to start with a caret (`^`), followed by a word character or a digit and then
-optionally followed by other word characters, digits or dashes. For example:
-
-    This is some text.[^1]. Other text.[^footnote].
-
-> Note that footnote markers cannot be used as part of the link text of a link because this would
-> lead to nested links which is not allowed in HTML.
-{: .information}
-
-Footnote markers with the same name will link to the same footnote definition. The actual naming of
-a footnote does not matter since the numbering of footnotes is controlled via the position of the
-footnote markers in the document (the first found footnote marker will get the number 1, the second 
-new footnote marker the number 2 and so on). If there is a footnote definition found for the
-identifier, a footnote will be created. Otherwise the footnote marker is not converted to a footnote
-link. Also note that all attributes set via a span IAL are ignored for a footnote marker!
-
-A footnote definition is used to define the content of a footnote and has the following structure:
-
-* The footnote name in square brackets, optionally indented up to three spaces,
-* then a colon and one or more optional spaces,
-* then the text of the footnote
-* and optionally more text on the following lines which have to follow the syntax for [standard code
-  blocks](#standard-code-blocks) (the leading four spaces/one tab are naturally stripped from the
-  text)
-
-> Footnote definitions are, despite being described here, non-content block-level elements.
-{: .information}
-
-The whole footnote content is treated like block-level text and can therefore contain any valid
-block-level element (also, any block-level element can be the first element). If you want to have a
-code block as first element, note that all leading spaces/tabs on the first line are stripped away.
-Here are some example footnote definitions:
-
-    [^1]: Some *crazy* footnote definition.
-
-    [^footnote]:
-        > Blockquotes can be in a footnote.
-
-            as well as code blocks
-
-        or, naturally, simple paragraphs.
-
-    [^other-note]:       no code block here (spaces are stripped away)
-
-    [^codeblock-note]:
-            this is now a code block (8 spaces indentation)
-
-It does not matter where you put a footnote definition in a kramdown document; the content of all
-referenced footnote definitions will be placed at the end of the kramdown document. Not referenced
-footnote definitions are ignored. If more than one footnote definitions have the same footnote name,
-all footnote definitions but the last are ignored.
-
-Although footnote definitions are non-content block-level elements, [block IALs](#block-ials) can be
-used on them to attach attributes. How these attributes are used depends on the converter.
-
-## Abbreviations
-
-> This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
-> the [PHP Markdown Extra] package.
-{: .markdown-difference}
-
-kramdown provides a syntax to assign the full phrase to an abbreviation. When writing the text, you
-don't need to do anything special. However, once you add abbreviation definitions, the
-abbreviations in the text get marked up automatically. Abbreviations can consist of any character
-except a closing bracket.
-
-An abbreviation definition is used to define the full phrase for an abbreviation and has the
-following structure:
-
-* An asterisk and the abbreviation in square brackets, optionally indented up to three
-  spaces,
-* then a colon and the full phrase of the abbreviation on one line (leading and trailing spaces are
-  stripped from the full phrase).
-
-Later abbreviation definitions for the same abbreviation override prior ones and it does not matter
-where you put an abbreviation definition in a kramdown document. Empty definitions are also allowed.
-
-Although abbreviation definitions are non-content block-level elements, [block IALs](#block-ials)
-can be used on them to specify additional attributes.
-
-Here are some examples:
-
-    This is some text not written in HTML but in another language!
-
-    *[another language]: It's called Markdown
-
-    *[HTML]: HyperTextMarkupLanguage
-    {:.mega-big}
-
-> Abbreviation definitions are, despite being described here, non-content block-level elements.
-{: .information}
-
-
-## Typographic Symbols
-
-> The original Markdown syntax does not support these transformations.
-{: .markdown-difference}
-
-kramdown converts the following plain ASCII character into their corresponding typographic symbols:
-
-* `---` will become an em-dash (like this ---)
-* `--` will become an en-dash (like this --)
-* `...` will become an ellipsis (like this ...)
-* `<<` will become a left guillemet (like this <<) -- an optional following space will become a
-  non-breakable space
-* `>>` will become a right guillemet (like this >>) -- an optional leading space will become a
-  non-breakable space
-
-The parser also replaces normal single `'` and double quotes `"` with "fancy quotes". There *may* be
-times when kramdown falsely replace the quotes. If this is the case, just \'escape\" the quotes and
-they won't be replaced with fancy ones.
-
-
-
-# Non-content elements
-
-This section describes the non-content elements that are used in kramdown documents, i.e. elements
-that don't provide content for the document but have other uses such as separating block-level
-elements or attaching attributes to elements.
-
-Three non-content block-level elements are not described here because they fit better where they
-are:
-
-* [link definitions](#link-definitions)
-* [footnote definitions](#footnotes)
-* [abbreviation definition](#abbreviations)
-
-
-## End-Of-Block Marker    {#eob-marker}
-
-> The EOB marker is not part of the standard Markdown syntax.
-{: .markdown-difference}
-
-The End-Of-Block (EOB) marker -- a `^` as first character on an otherwise empty line -- is a block
-level element that can be used to specify the end of a block-level element even if the block-level
-element, after which it is used, would continue otherwise. If there is no block-level element to
-end, the EOB marker is simply ignored.
-
-You won't find an EOB marker in most kramdown documents but sometimes it is necessary to use it to
-achieve the wanted results which would be impossible otherwise. However, it should only be used when
-absolutely necessary!
-
-For example, the following gives you one list with two items:
-
-    * list item one
-
-    * list item two
-
-By using an EOB marker, you can make two lists with one item each:
-
-    * list one
-    ^
-    * list two
-
-
-## Attribute List Definitions
-
-> This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
-> the [Maruku] package.
-{: .markdown-difference}
-
-This is an implementation of [Maruku]'s feature for adding attributes to block and span-level
-elements (the naming is also taken from Maruku). This block-level element is used to define
-attributes which can be referenced later. The [Block Inline Attribute List](#block-ials) is used to
-attach attributes to a block-level element and the [Span Inline Attribute List](#span-ials) is used
-to attach attributes to a span-level element.
-
-Following are some examples of attribute list definitions (ALDs) and afterwards comes the syntax
-explanation:
-
-    {:ref-name: #myid .my-class}
-    {:other: ref-name #id-of-other title="hallo you"}
-    {:test: key="value \" with quote" and other='quote brace \}'}
-
-An ALD line has the following structure:
-
-* a left brace, optionally preceded by up to three spaces,
-* followed by a colon, the reference name and another colon,
-* followed by attribute definitions (allowed characters are backslash-escaped closing braces or any
-  character except a not escaped closing brace),
-* followed by a closing brace and optional spaces until the end of the line.
-
-The reference name needs to start with a word character or a digit, optionally followed by other
-word characters, digits or dashes.
-
-There are four different types of attribute definitions which have to be separated by one or more
-spaces:
-
-references
-
-: This must be a valid reference name. It is used to reference an other ALD so that the attributes
-  of the other ALD are also included in this one. The reference name is ignored when collecting the
-  attributes if no attribute definition list with this reference name exists. For example, a simple
-  reference looks like `id`.
-
-key-value pairs
-
-: A key-value pair is defined by a key name, which must follow the rules for reference names, then
-  an equal sign and then the value in single or double quotes. If you need to use the value
-  delimiter (a single or a double quote) inside the value, you need to escape it with a backslash.
-  Key-value pairs can be used to specify arbitrary attributes for block or span-level elements. For
-  example, a key-value pair looks like `key1="bef \"quoted\" aft"` or `title='This is a title'`.
-
-ID name
-
-: An ID name is defined by using a hash and then the identifier name which needs to start with an
-  ASCII alphabetic character (A-Z or a-z), optionally followed by other ASCII characters, digits,
-  dashes or colons. This is a short hand for the key-value pair `id="IDNAME"` since this is often
-  used. The ID name specifies the unique ID of a block or span-level element. For example, an ID
-  name looks like `#myid`.
-
-class names
-
-: A class name is defined by using a dot and then the class name which may contain any character
-  except whitespace, the dot character and the hash character.
-
-  This is (almost, but not quite) a short hand for the key-value pair `class="class-name"`. Almost
-  because it actually means that the class name should be appended to the current value of the
-  `class` attribute. The following ALDs are all equivalent:
-
-      {:id: .cls1 .cls2}
-      {:id: class="cls1" .cls2}
-      {:id: class="something" class="cls1" .cls2}
-      {:id: class="cls1 cls2"}
-
-As can be seen from the example of the class names, attributes that are defined earlier are
-overwritten by ones with the same name defined later.
-
-> Also, everything in the attribute definitions part that does not match one of the above four types
-> is ignored.
-{:.information}
-
-If there is more than one ALD with the same reference name, the attribute definitions of all the
-ALDs are processed like they are defined in one ALD.
-
-
-## Inline Attribute Lists
-
-These elements are used to attach attributes to another element.
-
-### Block Inline Attribute Lists   {#block-ials}
-
-> This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
-> the [Maruku] package.
-{: .markdown-difference}
-
-This block-level element is used to attach attributes to another block-level element. A block inline
-attribute list (block IAL) has the same structure as an [ALD](#attribute-list-definitions) except
-that the colon/reference name/colon part is replaced by a colon. A block IAL (or two or more block
-IALs) has to be put directly before or after the block-level element to which the attributes should
-be attached. If a block IAL is directly after *and* before a block-level element, it is applied to
-preceding element. The block IAL is ignored in all other cases, for example, when the block IAL is
-surrounded by blank lines.
-
-Key-value pairs of an IAL take precedence over equally named key-value pairs in referenced ALDs.
-
-Here are some examples for block IALs:
-
-    A simple paragraph with an ID attribute.
-    {: #para-one}
-
-    > A blockquote with a title
-    {:title="The blockquote title"}
-    {: #myid}
-
-    {:.ruby}
-        Some code here
-
-### Span Inline Attribute Lists      {#span-ials}
-
-> This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
-> the [Maruku] package.
-{: .markdown-difference}
-
-This is a version of the [block inline attribute list](#block-ials) for span-level elements. It has
-the same structure as the block IAL except that leading and trailing spaces are not allowed. A span
-IAL (or two or more span IALs) has to be put directly after the span-level element to which it
-should be applied, no additional character is allowed between, otherwise it is ignored and only
-removed from the output.
-
-Here are some examples for span IALs:
-
-    This *is*{:.underline} some `code`{:#id}{:.class}.
-    A [link](test.html){:rel='something'} and some **tools**{:.tools}.
-
-The special span IAL `{::}` contains no attributes but doesn't generate a warning either. It can be
-used to separate consecutive elements that would be falsely parsed if not separated. Here is an use
-case:
-
-    This *is italic*{::}*marked*{:.special} text
-
-
-## Extensions
-
-> This syntax feature is not part of the original Markdown syntax.
-{: .markdown-difference}
-
-Extensions provide additional functionality but use the same syntax for it. They are available as
-block as well as span-level elements.
-
-The syntax for an extension is very similar to the syntax of [ALDs](#attribute-list-definitions).
-Here are some examples of how to specify extensions and afterwards is the syntax definition:
-
-    {::comment}
-    This text is completely ignored by kramdown - a comment in the text.
-    {:/comment}
-
-    Do you see {::comment}this text{:/comment}?
-    {::comment}some other comment{:/}
-
-    {::options key="val" /}
-
-An extension can be specified with or without a body. Therefore there exist a start and an end tag
-for extensions. The start tag has the following structure:
-
-* a left brace,
-* followed by two colons and the extension name,
-* optionally followed by a space and attribute definitions (allowed characters are backslash-escaped
-  closing braces or any character except a not escaped closing brace -- same as with ALDs),
-* followed by a slash and a right brace (in case the extension has no body) or only a right
-  brace (in case the extension has a body).
-
-The stop tag has the following structure:
-
-* a left brace,
-* followed by a colon and a slash,
-* optionally followed by the extension name,
-* followed by a right brace.
-
-A stop tag is only needed if the extension has a body!
-
-The above syntax can be used as is for span-level extensions. The starting and ending lines for block-level
-extensions are defined as:
-
-* The starting line consists of the extension start tag, optionally preceded by up to three spaces,
-  and followed by optional spaces until the end of the line.
-* The ending line consists of the extension stop tag, optionally preceded by up to three spaces,
-  and followed by optional spaces until the end of the line.
-
-If no end tag can be found for an extension start tag, the start tag is treated as if it has no
-body. If an invalid extension stop tag is found, it is ignored. If an invalid extension name is
-specified the extension (and the eventually specified body) are ignored.
-
-The following extensions can be used with kramdown:
-
-`comment`
-
-: Treat the body text as a comment which does not show in the output.
-
-`nomarkdown`
-
-: Don't process the body with kramdown but output it as-is. The attribute `type` specifies which
-  converters should output the body: if the attribute is missing, all converters should output it.
-  Otherwise the attribute value has to be a space separated list of converter names and these
-  converters should output the body.
-
-`options`
-
-: Should be used without a body since the body is ignored. Is used for setting the global options
-  for the kramdown processor (for example, to disable automatic header ID generation). Note that
-  options that are used by the parser are immediately effective whereas all other options are not!
-  This means, for example, that it is not possible to set converter options only for some part of a
-  kramdown document.
-
-
-
-{include_file: doc/links.markdown}