RubyGems - kramdown - Versions diffs - 0.1.0 → 0.2.0 - Mend

kramdown 0.1.0 → 0.2.0

Potentially problematic release.

This version of kramdown might be problematic. Click here for more details.

Files changed (87) hide show

data/VERSION CHANGED Viewed

	@@ -1 +1 @@
1	- 0.1.0
1	+ 0.2.0

data/doc/default.template CHANGED Viewed

@@ -4,19 +4,19 @@
     <meta http-equiv="content-type" content="text/html; charset=utf-8" />
     <meta name="author" content="Thomas Leitner" />
     <meta name="copyright" content="2009 Thomas Leitner" />
-    <meta name="description" content="ruby-amt is a library for accessing Intel AMT via SOAP" />
-    <meta name="keywords" content="ruby-amt,ruby amt,ruby vpro" />
+    <meta name="description" content="kramdown is a fast, pure-Ruby Markdown-superset converter" />
+    <meta name="keywords" content="ruby, kramdown, markdown, text markup" />
     <link href="{relocatable: default.css}" type="text/css" rel="stylesheet" media="screen,projection" />
     <link href="{relocatable: news.atom}" type="application/atom+xml" rel="alternate" />
-    <title>{title:} | ruby-amt</title>
+    <title>{title:} | kramdown</title>
   </head>
   <body>
     <div id="layout">
       <div id="header">
-        <h1 id="logo"><a href="{relocatable: /}" title="Homepage">ruby-amt <span class='slogan'>library for controlling Intel AMT devies via SOAP</span></a></h1>
+        <h1 id="logo"><a href="{relocatable: /}" title="Homepage">kramdown <span class='slogan'>fast, pure-Ruby Markdown-superset converter</span></a></h1>
         <hr class="noscreen" />
       </div>

data/doc/index.page CHANGED Viewed

@@ -73,15 +73,16 @@ and [mailing lists][ml] available if you have any questions!
 ## Welcome to the kramdown site
-kramdown is a *free* GPL-licensed [Ruby](http://www.ruby-lang.org) library for parsing Markdown-like
-syntax. It is completely written in Ruby, supports standard Markdown (with some minor modifications)
-and various extensions that have been made popular by the [PHP Markdown Extra] package and [Maruku].
+kramdown is a *free* GPL-licensed [Ruby](http://www.ruby-lang.org) library for parsing a superset of
+Markdown. It is completely written in Ruby, supports standard Markdown (with some minor
+modifications) and various extensions that have been made popular by the [PHP Markdown Extra]
+package and [Maruku].
 It is probably the fastest pure-Ruby Markdown converter available (November 2009), being 5x faster
 than [Maruku] and about 10x faster than [BlueFeather].
 <div class="a-center">
-The latest version of kramdown is <b>0.1.0</b> and it was released on <b>2009-11-21</b>.
+The latest version of kramdown is <b>0.2.0</b> and it was released on <b>2009-12-03</b>.
 </div>
 [PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/

data/doc/news.feed CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 title: kramdown News
-description: kramdown - a fast, pure Ruby Markdown+extensions converter
+description: kramdown - a fast, pure Ruby Markdown-superset converter
 site_url: http://kramdown.rubyforge.org/
 author: Thomas Leitner
 author_url: http://kramdown.rubyforge.org

data/doc/quickref.page CHANGED Viewed

@@ -5,9 +5,12 @@ sort_info: 9
 ---
 # Quick Reference
-Below are examples of all available structural elements that can be used in kramdown text. Note,
-that only the most basic syntax information is given. However, a link to the detailed syntax for
-each element is provided.
+Below are examples of all available structural elements that can be used in a kramdown text. Since
+the kramdown syntax is a superset of the Markdown syntax, only a small part of the available syntax
+is not available in standard Markdown syntax. Note, that only the most basic syntax information is
+given. However, a link to the detailed syntax for each element is provided (which also details the
+differences to the standard Markdown syntax). The quick reference is for version **<%=
+Kramdown::VERSION %>** of the syntax documentation.
 kramdown has two main classes of elements: block and span level elements. Block level elements are
 used to create paragraphs, headers, lists and so on whereas span level elements are used to markup
@@ -16,18 +19,14 @@ text phrases as emphasized, as a link and so on.
 All examples below feature the kramdown source, the converted HTML source and the output as it
 appears in the browser. This looks like this:
-{::nokramdown:}
 <div class="kdexample">
-<pre class="kdexample-before"><code>kramdown example code
-</code></pre>
-<pre class="kdexample-after-source"><code>Example code converted to HTML
-</code></pre>
+<pre class="kdexample-before"><code>kramdown example code</code></pre>
+<pre class="kdexample-after-source"><code>Example code converted to HTML</code></pre>
 <div class="kdexample-after-live">
 Live browser view of example code
 </div>
 </div>
 <div class="clear"></div>
-{::nokramdown:}
 # Block Level Elements - Main Structural Elements
@@ -81,16 +80,15 @@ Second level header
 ###### H6 header
 {::kdexample:}
-If you set the option `auto_ids` to `true` (for example, by using the `kdoptions` extension, see
-[Extension Blocks](#extension-blocks)), then all headers are automatically given header IDs based on
-the header text:
+If you set the option `auto_ids` to `false` (for example, by using the `options` extension, see
+[Extension Blocks](#extension-blocks)), then the automatic header ID generation is turned off:
 {::kdexample:}
-# A header without an ID
+# A header with an ID
-{::kdoptions:: auto_ids="true"}
+{::options:: auto_ids="false"}
-# A header with an ID
+# A header without an ID
 {::kdexample:}
@@ -211,18 +209,67 @@ space. Apart from that unordered lists follow the same rules as ordered lists:
 - Item three
 {::kdexample:}
+## Definition Lists
+{::kdlink:: #definition-lists part="definition lists"}
+A definition list works similar to a normal list and is used to associate definitions with terms.
+Definition lists are started when a normal paragraph is followed by a line starting with a colon and
+then the definition text. One term can have many definitions and multiple terms can have the same
+definition. Each line of the preceding paragraph is assumed to contain one term, for example:
+{::kdexample:}
+term
+: definition
+: another definition
+another term
+and another term
+: and a definition for the term
+{::kdexample:}
+If you insert a blank line before a definition (note: there must only be one blank line between the
+terms and the first definition), the definition will be wrapped in a paragraph:
+{::kdexample:}
+term
+: definition
+: definition
+{::kdexample:}
+Each term can be styled using span level elements and each definition is parsed as block level
+elements, ie. you can use any block level in a definition. Just use the same indent for the lines
+following the definition line:
+{::kdexample:}
+This *is* a term
+: This will be a para
+  > a blockquote
+  # A header
+{::kdexample:}
 ## HTML elements
+{::kdlink:: #html-blocks part="HTML blocks"}
 kramdown allows you to use block level HTML tags (`div`, `p`, `pre`, ...) to markup whole blocks of
-text -- just start a line with a block level HTML tag. The content of a block level HTML tag is
-parsed by kramdown either as block level or span level text, depending on the tag:
+text -- just start a line with a block level HTML tag. kramdown syntax is normally not processed
+inside an HTML tag but this can be changed with the `parse_block_html` option. If this options is
+set to `true`, then the content of a block level HTML tag is parsed by kramdown either as block
+level or span level text, depending on the tag:
 {::kdexample:}
 <div style="float: right">
-Something that stays right.
+Something that stays right and is not wrapped in a para.
+</div>
+{::options:: parse_block_html="true"}
+<div>
+This is wrapped in a para.
 </div>
-Normal text flow.
 <p>
 This can contain only *span* level elements.
 </p>
@@ -299,9 +346,9 @@ completely ignored.
 {::comment:}
 ... paragraph continues here.
-{::nokramdown:}
+{::nomarkdown:}
 This is not parsed *by* kramdown
-{::nokramdown:}
+{::nomarkdown:}
 {::kdexample:}
 As one can see from the above example, the syntax for extension blocks is virtually the same as for
@@ -311,13 +358,13 @@ body text and continues until a matching ending line (as in the example above).
 used, then the extension does not have a body, for example:
 {::kdexample:}
-# Header without id
-{::kdoptions:: auto_ids="true"}
 # Header with id
-{::kdoptions:: auto_ids="false"}
+{::options:: auto_ids="false"}
 # Header without id
+{::options:: auto_ids="true"}
+# Header with id
 {::kdexample:}

data/doc/syntax.page CHANGED Viewed

@@ -3,12 +3,13 @@ title: Syntax
 in_menu: true
 sort_info: 10
 ---
+This is version **<%= Kramdown::VERSION %>** of the syntax documentation.
 Table of Contents:
-{::nokramdown:}
+{::nomarkdown:}
 {menu: {used_nodes: fragments, min_levels: 3}}
-{::nokramdown:}
+{::nomarkdown:}
 # kramdown Syntax
@@ -120,13 +121,11 @@ meaning:
 * 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.
+would continue otherwise. If there is no block 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.
@@ -155,7 +154,7 @@ separate two consecutive paragraphs from each other by using one or more blank l
 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.
+ignored. Leading and trailing spaces will be stripped from the paragraph text.
 The following gives you an example of how paragraphs look like:
@@ -173,6 +172,8 @@ The following gives you an example of how paragraphs look like:
 kramdown supports Setext style and atx style headers.
+### Setext Style
 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
@@ -221,6 +222,8 @@ One might ask if this represents two paragraphs separated by a horizontal line o
 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 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
@@ -237,8 +240,11 @@ close the header. Any leading or trailing spaces are stripped from the header te
 > 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:
+### Automatic Generation of Header IDs
+kramdown supports the automatic generation of header IDs if the option `:auto_ids` is set to `true`
+(which is the default). 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.
@@ -277,6 +283,24 @@ Following are some examples of header texts and their respective generated IDs:
 > text is converted to an identifier are based on the rules specified by [Pandoc].
 {: .markdown-difference}
+### Manually Specifying a Header ID
+Additionally, kramdown supports a nice way for setting the header ID which is available in [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
@@ -330,6 +354,8 @@ Code blocks can be used to represent verbatim text like markup, HTML or a progra
 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.
+### Standard Code Block
 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
@@ -346,6 +372,12 @@ separate the two:
     ^
         This one is separate.
+### Fenced Code Block
+> 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
@@ -368,9 +400,7 @@ example:
 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}
+### Showing Whitespace in a Code Block
 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
@@ -389,10 +419,10 @@ Here is an example:
 ## 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:
+A horizontal rule is created by using three or more asterisks, dashes or underscores (these may not
+be mixed on one 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:
     * * *
@@ -405,6 +435,11 @@ create a horizontal rule:
 ## 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
@@ -477,11 +512,12 @@ list text is followed by one or more blank lines, it will be wrapped in a paragr
     * 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. 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:
+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.
@@ -577,21 +613,112 @@ useful when the paragraph starts with something looking like a list item marker)
     \- others say that, too!
+### 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
+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.
+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. If
+one of the following lines does not have the needed amount of indentation, it is not treated as part
+of the defintion. 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 sothat they first characters align. This tells kramdown
+      that the lines belong to the definition.
+    :       This is the another defintion 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!
+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 defintion 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.
 ## 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>`.
+kramdown encounters a line beginning with an HTML tag that is *not* a span level HTML tag (`div`,
+`p`, `pre`, ...) -- or with a general XML tag -- which may be indented up to three spaces. After
+that any combination of text and HTML tags are allowed, with HTML span tags being treated as text.
+Each HTML block tag must appear completely on the line, it may not be broken across several lines!
+If a block HTML tag is not closed on the same line, the HTML block continues till the HTML block
+line with the corresponding closing tag. Note that only correct XHTML is supported! This means that
+you have to use, for example, `<hr />` instead of `<hr>` (although kramdown tries to fix such things
+if possible).
+By default, kramdown does not parse HTML blocks, i.e. when a block level HTML tag is encountered
+only HTML block lines are parsed and everything else is treated as raw text. This will be done until
+the closing tag for the outermost HTML tag is found (or until the end of the document if the closing
+HTML tag does not exist). However, this can be configured with the `:parse_block_html` option. If
+this is set to `true`, then syntax parsing in HTML blocks is enabled. All the examples below assume
+that `:parse_block_html` is set to `true`. 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 block
+  lines) is done inside that HTML tag.
+* 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.
+Note, however, that text that appears on an HTML block starting or ending line is not parsed as
+block level element even if the rest of the HTML block is! It is parsed as span level text
+nonetheless.
+If an invalid closing tag is found on an HTML block line while no HTML block is active, it is
+ignored.
 > 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.
+> you to use Markdown syntax in HTML blocks which is allowed with kramdown.
 {: .markdown-difference}
 Here is a simple example:
@@ -604,7 +731,7 @@ Here is a simple example:
 ^
     <p>This is a para.</p>
     <div>
-    <p>Something in here.</p>
+      <p>Something in here.</p>
     </div>
     <p>Other para.</p>
@@ -629,40 +756,47 @@ When you specify an HTML block don't forget that the first column does not chang
       </div>
     </div>
-If you don't use valid XHTML tags, you won't get expected result (note the invalid `<br>` tag):
+If you don't use valid XHTML tags, you sometimes won't get the expected result. However, kramdown
+tries to fix broken HTML if possible (note the automatically closed `<hr />` tag):
     This is a para.
     <div>
-    Something is<br>
-    broken here.
+    Something is broken here.
+    <hr>
     </div>
-    This won't be a para.
+    This is a para.
 ^
     <p>This is a para.</p>
     <div>
-    <p>Something is&lt;br&gt;
-    broken here.</p>
+      <p>Something is broken here.</p>
+      <hr />
     </div>
-    This won't be a para.
+    <p>This is a para.</p>
 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:
+nesting and invalidly used end tags are removed from the output:
     This is a para.
-    <div><div class="clear"/>
+    <div><div class="clear"></div>
     Another para.
     </p>
 ^
     <p>This is a para.</p>
-    <div><div class="clear"/>
+    <div><div class="clear"></div>
       <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.
+parsed at all. General XML tags are also not parsed at all by default.
+The following HTML tags count as span level HTML tags and *won't* start an HTML block if found on an
+HTML block line. All other HTML tags and general XML tags will start an HTML block!
+    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
 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
@@ -677,7 +811,6 @@ comment till the end of the line are ignored. kramdown syntax in PIs/XML comment
     Another para.
 ## Attribute List Definitions
 > This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
@@ -712,31 +845,31 @@ characters, digits or dashes.
 There are four different types of attribute definitions which have to be separated by one or more
 spaces:
-*   references
+references
-    This must be a valid reference name. It is used to reference an other ALD sothat the attributes
+:   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
+key-value pairs
-    A key-value pair is defined by a key name, which must follow the rules for reference names, then
+:   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
+ID name
-    An ID name is defined by using a hash and then the identifier name which must follow the rules
+:   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
+class names
-    A class name is definied by using a dot and then the class name. This is (almost, but not quite)
+:   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:
@@ -781,25 +914,26 @@ Here are some examples for block IALs:
         Some code here
     {:.ruby}
-TODO: special case for atx style headers.
 ## Extension Blocks
+> This syntax feature is not part of the original Markdown syntax.
+{: .markdown-difference}
 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
+Without a body
-    The extension block line has the same structure as an [ALD](#attribute_list_definitions) except
+:   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
+With a body
-    The starting and ending lines of an extension block with a body have the same structure as an
+:   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
@@ -809,17 +943,17 @@ An extension block has two forms, one with a body and one without a body:
 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`
+`comment`
-    Treats the body text as a comment which does not show in the output.
+:   Treats the body text as a comment which does not show in the output.
-*   `nokramdown`
+`nomarkdown`
-    The body is not processed with kramdown but output as-is.
+:   The body is not processed with kramdown but output as-is.
-*   `kdoptions`
+`options`
-    Should be used without a body since the body is ignored. Is used for setting options for the
+:   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:
@@ -848,6 +982,8 @@ output.
 Two styles of links are supported: inline and reference.
+### 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.
@@ -873,6 +1009,8 @@ Notes:
 * The link title may not contain its delimiters and may not be empty.
+### 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 indentifier may only contain
@@ -888,6 +1026,8 @@ second pair of square brackets, the link text is converted to a valid link ident
 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.
+### 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:
@@ -909,6 +1049,8 @@ The link definition has the following structure:
 > allowed for consistency with the inline title.
 {: .markdown-difference}
+### 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
@@ -1001,15 +1143,45 @@ literal meaning of a backtick you can backslash-escape it:
 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>`.
+you have to use, for example, `<br />` instead of `<br>`.
+By default, kramdown parses kramdown syntax inside HTML spans. 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.
-Processing instructions and XML comments can also be used (their content is not parsed).
+* If an HTML tag has an attribute `markdown="1"`, then the content of the tag is parsed as span
+  level elements.
-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.
+* 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.
-Unclosed HTML tags as well as invalidly used end tags are escaped.
+* 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 sothat 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 HTML tags as well as invalidly used end tags or block HTML tags are escaped.
+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>
 ## Footnotes