kramdown 0.1.0

data/doc/syntax.page

@@ -0,0 +1,1089 @@
+---
+title: Syntax
+in_menu: true
+sort_info: 10
+---
+
+Table of Contents:
+
+{::nokramdown:}
+{menu: {used_nodes: fragments, min_levels: 3}}
+{::nokramdown:}
+
+# kramdown Syntax
+
+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 differes from the Markdown syntax are highlighted.
+
+Following is the complete syntax definition so that you know what you will get when a kramdown
+document is converted to HTML. There are basically two types of elements: block level elements
+(paragraphs, blockquotes, ...) and span level elements (emphasis, links, ...). Each has its own
+section.
+
+[Maruku]: http://maruku.rubyforge.org
+[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
+[Pandoc]: http://johnmacfarlane.net/pandoc/
+
+
+## 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 Escaping and Escaping
+
+There are three characters in HTML syntax that need special treatment: `<`, `>` and `&`. When these
+characters are used inside a code block or code span, they are always automatically escaped to their
+HTML entity counterparts.
+
+When used inside the normal text flow:
+
+* `<` and `>` are always escaped except if they are part of an HTML tag, an XML processing
+  instruction/comment or an autolink.
+* `&` is escaped if it is not part of an HTML entity.
+
+For example, the following fragment:
+
+    This is the A&O. &copy; 2008 by me
+    0 < 1 < 2 and 2 > 1 > 0
+
+will be converted to:
+
+    <p>This is the A&amp;O. &copy; 2008 by me
+    0 &lt; 1 &lt; 2 and 2 &gt; 1 &gt; 0</p>
+
+Since kramdown also uses some characters to mark-up the text, there need to be a way to escape these
+special characters sothat they can have their normal meaning. This can be done by using backslash
+escapes. For example, you can use a literal backtick like this:
+
+    This \`is not a code\` span!
+
+Following is a list of all those characters (character sequences) that can be escaped:
+
+    \         backslash
+    .         period
+    *         asterisk
+    _         underscore
+    +         plus
+    -         minus
+    `         backtick
+    ()[]{}    parens/brackets/braces
+    #         hash
+    !         bang
+    <<        left guillemet
+    >>        right guillemet
+
+
+## Typographic Symbols
+
+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 original Markdown program does not do this transformations.
+{: .markdown-difference}
+
+
+# Block Level Elements
+
+Block level elements are used to structure the content. They can mark up some text, for example, as
+code, as a quote or as list items.
+
+You will often find references to the "first column" or "first character" of a line in the 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.
+
+
+## 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 mostly used to visually 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 paragraphs -- see the [paragraphs section](#paragraphs)
+* When used in headers -- see the [headers section](#headers)
+* When used in lists -- see the [lists section](#lists)
+
+
+
+## End-Of-Block Marker
+
+The End-Of-Block (EOB) marker -- a `^` as first character on an otherwise empty line -- 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 to end, the EOB marker is simply ignored and the line
+is considered a blank line.
+
+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.
+
+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 each one item:
+
+    * list one
+    ^
+    * list two
+
+> The EOB marker is not part of the standard Markdown syntax.
+{: .markdown-difference}
+
+
+## Paragraphs
+
+Paragraphs are the most used block level elements. One or more consecutive lines of text are
+interpreted as one paragraph. Every line of a paragraph may be indented up to three spaces. 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. If you want to have an explicit
+line break (ie. 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.
+
+The following gives you an example of how paragraphs look like:
+
+    This para line starts at the first column. However,
+       the lines can be indented up to three spaces.
+    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 Setext style and atx style headers.
+
+Setext style headers are specified by a blank line (except at the beginning of a document), a line
+of text (the header text) followed by 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, 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
+    =
+
+As mentioned you need to insert a blank line before 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 approriate.
+
+> The original Markdown syntax allows one to omit the blank line before a Setext header. However,
+> this makes reading the document harder than necessary and is therefore 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 line 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 headers can be specified by a blank line (except at the beginning of a document), a line
+with 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 till 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}
+
+kramdown supports the automatic generation of header IDs if the option `:auto_ids` is set to `true`.
+This is done by converting the untransformed, ie. plain, header text via the following steps:
+
+* All characters except letters, numbers, spaces and dashes are removed.
+* All characters from the start of the line till the first letter are removed.
+* Everything except letters and numbers is converted to dashes.
+* Everything is downcased.
+* If nothing is left, the identifier `section` is used.
+* If a such created identifier already exists, a dash and a sequential number is added (first `-1`,
+  then `-2` and so on).
+
+Following are some examples of header texts and their respective generated IDs:
+
+    # This is a header
+    auto_id: this-is-a-header
+
+    ## 12. Another one 1 here
+    auto_id: another-one-1-here
+
+    ### Do ^& it now
+    auto_id: do--it-now
+
+    Hallo
+    =====
+    auto_id: hallo
+
+    Not now
+    -------
+    auto_id: not-now
+
+    # Hallo
+    auto_id: hallo-1
+
+    # 123456789
+    auto_id: section
+
+> The automatic creation of header IDs is not part of standard Markdown. The rules on how header
+> text is converted to an identifier are based on the rules specified by [Pandoc].
+{: .markdown-difference}
+
+
+## Blockquotes
+
+A blockquote is started using the `>` marker followed by an optional space. The marker itself may be
+indented up to three spaces. All following lines that are also started with the blockquote marker
+belong to the blockquote. 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.
+    >
+    > 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 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 will have to be
+indented with five spaces or one space and one tab, like this:
+
+    > A code block:
+    >
+    >     ruby -e 'puts :works'
+
+> The original Markdown syntax allowed "lazy" blockquotes, ie. blockquotes where only the first line
+> needs a blockquote marker. This is disallowed in kramdown, you always need to use a blockquote
+> marker! The rational behind this is that most email programs and good text editors put the `>`
+> maker automatically before every quoted line and that things like the following work like
+> expected:
+>
+>     > > This is some quoted text.
+>     > > Spanning multiple lines.
+>     > This is the answer to the quoted text above.
+>     This is just a normal paragraph, with the answer to the above.
+{: .markdown-difference}
+
+
+## Code Blocks
+
+Code blocks can be used to represent verbatim text like markup, HTML or a program fragment. No
+syntax is parsed within a code block, only `<`, `>` and `&` are substituted by their respective HTML
+counterparts. A code block is wrapped in both `<pre>` and  `<code>` tags.
+
+A code block can be started by using four spaces or one tab and then the text of the code block. All
+following lines that adhere to this syntax belong to the same code block. The indentation (four
+spaces or one tab) is stripped from the text. Note that blank lines don't separate consecutive code
+blocks:
+
+        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 to
+separate the two:
+
+        Here comes some code
+    ^
+        This one is separate.
+
+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.
+
+> The alternative syntax is not part of the original Markdown syntax. The idea and syntax comes from
+> the [PHP Markdown Extra] package.
+{: .markdown-difference}
+
+If you add the class `show-whitespaces` to a code block (using a [block
+IAL](#block_inline_attribute_lists)), all spaces are replaced with `&sdot;` and additionally spaces
+and tabs in the code block are marked up using HTML `span` tags and the CSS classes:
+
+* `ws-space-l`, `ws-tab-l`: leading spaces/tabs
+* `ws-space-r`, `ws-tab-r`: trailing spaces/tabs
+* `ws-space`, `ws-tab`: spaces/tabs in between
+
+Here is an example:
+
+    	  leading tab	and space
+    trailing   tab and space    	
+{: .show-whitespaces}
+
+
+## Horizontal Rules
+
+A horizontal rule is created by using three or more asterisks, dashes or underscores, 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:
+
+    * * *
+
+    ---
+
+      _  _  _  _
+
+    ---------------
+
+
+## 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 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. If a line does not
+have the needed amount of indentation, it is not treated as list item content. 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
+      lines have to be indented 2 spaces sothat they first characters align. This tells kramdown
+      that the lines belong to the list item.
+    *       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.
+
+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!
+
+> 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}
+
+When using tabs for indenting the content of a list item, remember that tab stops occur at multiples
+of four. Tabs are 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 two 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 and don't have the tab
+stops set to multiples of four! 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
+
+In the above example, the first list item text will be wrapped in a paragraph tag since it is
+followed by a blank line. 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 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 follow a list item with an indentation of four or less
+immediately with a code block. 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.
+
+> The original Markdown syntax allows you to be lazy when you just use text for a list item. So the
+> following is possible with Markdown:
+>
+>     * First list item
+>     continued here
+>     *   Second list item
+>       continued here.
+>
+> This kind of syntax is disallowed in kramdown.
+{: .markdown-difference}
+
+If you want to have one list directly after another one (both with the same list type, ie. ordered
+or unordered), you need to use an EOB marker to separate the two:
+
+    * List one
+    ^
+    * List two
+
+It is possible that a line gets parsed as ordered or unordered list although it shouldn't. This
+would be the case in the following example:
+
+    I have read the book
+    1984. It was great
+    - others say that, too!
+
+Therefore you have to insert a blank line after a paragraph if you want to follow the paragraph with
+a list. The only exception to this rule is when you want to create a compact nested list, i.e. a
+list where the text is not wrapped in paragraphs:
+
+    *   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.
+
+Another way to remedy the problem with the list item marker appearing in plain text is by escaping
+the period in an ordered list or the list item marker in an unordered list (this is especially
+useful when the paragraph starts with something looking like a list item marker):
+
+    1984\. It was great
+    \- others say that, too!
+
+
+## HTML Blocks
+
+There is no problem mixing HTML tags into a kramdown document. An HTML block is started when
+kramdown encounters a line beginning with a block level HTML tag (`div`, `p`, `pre`, ...) -- or with
+a general XML tag -- which may be indented up to three spaces. The line may contain multiple block
+level HTML tags (no span level HTML tags) but each tag must appear completely on the line! The HTML
+block continues till the matching end tag of the first HTML tag is encountered (i.e. till an HTML
+block line with the matching end tag is found). kramdown syntax is processed in HTML blocks. Note
+that only correct XHTML is supported! This means that you have to use, for example, `<br/>` instead
+of `<br>`.
+
+> The original Markdown syntax specifies that an HTML block must start at the left margin, ie. 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.
+{: .markdown-difference}
+
+Here is a simple example:
+
+    This is a para.
+    <div>
+    Something in here.
+    </div>
+    Other para.
+^
+    <p>This is a para.</p>
+    <div>
+    <p>Something in here.</p>
+    </div>
+    <p>Other para.</p>
+
+See how the content of the `div` tag is wrapped in a paragraph!
+
+You can also use several HTML tags at once:
+
+    <div id="content"><div id="layers"><div id="layer1">
+    This is a para in the `layer1` div.
+    </div>
+    This is a para in the `layers` div.
+    </div></div>
+    This is a para outside the HTML block.
+
+When you specify an HTML block don't forget that the first column does not change:
+
+    This is a para.
+    <div><h1>some header</h1>
+        code block (indented four spaces)
+      <div>
+        also a code block
+      </div>
+    </div>
+
+If you don't use valid XHTML tags, you won't get expected result (note the invalid `<br>` tag):
+
+    This is a para.
+    <div>
+    Something is<br>
+    broken here.
+    </div>
+    This won't be a para.
+^
+    <p>This is a para.</p>
+    <div>
+    <p>Something is&lt;br&gt;
+    broken here.</p>
+    </div>
+    This won't be a para.
+
+Unclosed block level HTML tags are correctly closed at the end of the document to ensure correct
+nesting and invalidly used end tags are escaped:
+
+    This is a para.
+    <div><div class="clear"/>
+    Another para.
+    </p>
+^
+    <p>This is a para.</p>
+    <div><div class="clear"/>
+      <p>Another para.</p>
+    &lt;/p&gt;
+    </div>
+
+The content of a HTML tag is either parsed as block level elements, span level elements or is not
+parsed at all depending on the tag encountered. For example, a `<div>` tag contains block level
+elements, a `<p>` tag contains span level elements and the contents of a `<script>` tag is not
+parsed at all.
+
+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. All characters from the end of a PI/XML
+comment till the end of the line are ignored. kramdown syntax in PIs/XML comments is not processed:
+
+    This is a para.
+    <!-- a *comment* -->
+    <? a processing `instruction`
+       spanning multiple lines
+    ?>
+    Another para.
+
+
+
+## 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_inline_attribute_lists) is used to attach attributes to a block level element and the
+[Span Inline Attribute List](#span_inline_attribute_lists) 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 an unescaped closing brace),
+* followed by a closing brace and optional spaces till 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 sothat 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 arbitray 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 must follow the rules
+    for reference names. 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 definied by using a dot and then the class name. 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.
+
+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.
+
+
+## Block Inline Attribute Lists
+
+> 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 a 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 after the block level element to which the attributes should be
+attached, otherwise it is ignored. This is, for example, the case when there is a blank line between
+the block level element and the IAL.
+
+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}
+
+        Some code here
+    {:.ruby}
+
+TODO: special case for atx style headers.
+
+
+## Extension Blocks
+
+Extension blocks can be used, for example, to treat whole sections of text specially. For example,
+one could write an extension that highlights a code fragment specified in an extension block.
+
+An extension block has two forms, one with a body and one without a body:
+
+*   Without a body
+
+    The extension block line has the same structure as an [ALD](#attribute_list_definitions) except
+    that the reference name needs to prefixed and postfixed with `:` and identifies the extension to
+    be used. Attributes can be defined like it is done for an ALD.
+
+*   With a body
+
+    The starting and ending lines of an extension block with a body have the same structure as an
+    [ALD](#attribute_list_definitions) except that the reference name needs to prefixed with `:` and
+    identifies the extension to be used; attributes can be defined on the starting or ending line.
+    The text between the starting and ending line is passed to the extension and not parsed by
+    kramdown. If no ending line is found, the starting line is ignored and the body is parsed
+    normally by kramdown.
+
+If the specified extension is not found, a warning is shown and the whole extension block including
+the body is ignored. The following extensions are builtin:
+
+*   `comment`
+
+    Treats the body text as a comment which does not show in the output.
+
+*   `nokramdown`
+
+    The body is not processed with kramdown but output as-is.
+
+*   `kdoptions`
+
+    Should be used without a body since the body is ignored. Is used for setting options for the
+    kramdown processor (for example, to enable automatic header ID generation).
+
+Here are some examples for how extension blocks look like:
+
+    {::toc::}
+
+    The above extension block could be replaced by a table of contents.
+
+    {::comment:}
+    This text is completely ignored by kramdown - a comment in the text.
+    {::comment:}
+
+
+
+# Span Level Elements
+
+These elements are 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
+
+Two styles of links are supported: inline and reference.
+
+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 URL must not contain any spaces and it has to contain properly nested parentheses if no
+  title is specified, or the link URL must be contained in angle brackets (then spaces and
+  incorrectly nested parentheses are allowed). There must not be any spaces before the link URL, and
+  if no title is specified, no spaces are allowed between the link URL and the closing parenthesis.
+
+* The link title may not contain its delimiters and may not be empty.
+
+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 indentifier may only contain
+numbers, letters, spaces (line breaks and tabs are converted to spaces, multiple spaces are
+compressed to one) and punctuation characters (ie. `_.:,;!?-`) and is not case sensitive. 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 (ie. 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.
+
+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, 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 spaces/tabs,
+* then the link URL which must not contain any spaces or a left angle bracket, the link URL which may
+  contain spaces 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}
+
+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].
+
+The link definition for images is exactly the same as the link definition for normal links.
+
+
+## Emphasis
+
+kramdown uses the HTML elements `em` and `strong` to style emphasized text parts. Text parts that
+are surrounded with single asterisks `*` or underscores `_` are wrapped in `em` tags, text parts
+surrounded with two asterisks or underscores are wrapped in `strong` tags. Surrounded means that the
+starting delimiter must not be followed by a space and that the stopping delimiter must not be
+preceeded by a space. For example:
+
+    *some text*
+    _some text_
+    **some text**
+    __some text__
+
+will produce the following output:
+
+    <em>some text</em>
+    <em>some text</em>
+    <strong>some text</strong>
+    <strong>some text</strong>
+
+The asterisk form is also allowed within a single word:
+
+    This is un*believe*able! This d_oe_s not work!
+
+Text emphasized with different delimiters can be nested but you can't nest emphasized text with the
+same delimiters:
+
+    This is a ***strong and emphasized*** text.
+    This **is __very__ strong**.
+    This **is **very** strong**.
+
+will produce the following output:
+
+    <p>This is a <strong><em>strong and emphasized</em></strong> text.
+    This <strong>is <strong>very</strong> strong</strong>.
+    This <strong>is </strong>very<strong> strong</strong>.</p>
+
+Notice the difference between the second and the third line!
+
+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 element. You can markup a text part as code span
+by surrounding it with backticks `` ` ``. For example:
+
+    Use `<html>` tags for this.
+
+The special characters `<`, `>` and `&` are substituted by their respective HTML counterparts (same
+behaviour as seen with the block level code block element).
+
+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!).
+
+will produce:
+
+    <p>Here is a literal <code>`</code> backtick.</p>
+    <p>And here is <code> `some` </code> text (note the two spaces!).</p>
+
+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!
+
+
+## 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>`.
+
+Processing instructions and XML comments can also be used (their content is not parsed).
+
+Span level HTML tags (opening or closing), span level PIs and span level XML comments have to be
+preceded by at least one non whitespace character on the same line sothat kramdown correctly
+recognizes them as span level element and not as block level element.
+
+Unclosed HTML tags as well as invalidly used end tags are escaped.
+
+
+## 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 simliar 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].
+
+The footnote name has to be unique in the whole kramdown document. Therefore you can't link to the
+same footnote definition twice. 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 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 have to be indented by four spaces or
+  one tab (like with list items).
+
+> Footnote definitions are, despite being described here, 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
+foot note definitions are ignored. If more than one footnote definitions have the same footnote
+name, all footnote definitions but the last are ignored.
+
+
+## Span Inline Attribute Lists
+
+> 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_inline_attribute_lists) 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,
+no additional character is allowed between.
+
+Here are some examples for span IALs:
+
+    This *is*{:.underline} some `code`{:#id}{:.class}.
+    A [link](test.html){:rel='something'} and some **tools**{:.tools}.