kramdown 0.6.0 → 0.7.0

data/doc/syntax.page

@@ -17,19 +17,16 @@ it strives to provide a strict syntax with definite rules and therefore isn't co
 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 so that you know what you will get when a kramdown
-document is converted to, for example, HTML.
-
-[Maruku]: http://maruku.rubyforge.org
-[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
-[Pandoc]: http://johnmacfarlane.net/pandoc/
+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. It consists of two types of elements, block level
-elements and span level elements:
+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.
@@ -38,6 +35,12 @@ elements and span level elements:
 
 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.
+
 
 ### Usage of Tabs
 
@@ -57,9 +60,9 @@ This means, for example, that you can just use `<`, `>` and `&` in a kramdown do
 think about when to use their HTML entity counterparts. However, if you *do use* HTML entitys 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 need 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 backtick like this:
+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 backtick like this:
 
     This \`is not a code\` span!
 
@@ -84,16 +87,10 @@ Following is a list of all the characters (character sequences) that can be esca
     $         dollar sign
 
 
-# Block Level Elements
+# Structural Elements
 
-Block level elements 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.
-
-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.
+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
@@ -109,33 +106,6 @@ meaning:
 * When used in lists -- see the [lists section](#lists)
 
 
-## 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 -- 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 necesary!
-
-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
-
-
 ## Paragraphs
 
 Paragraphs are the most used block level elements. One or more consecutive lines of text are
@@ -160,7 +130,8 @@ The following gives you an example of how paragraphs look like:
 
 ## Headers
 
-kramdown supports so called Setext style and atx style headers.
+kramdown supports so called Setext style and atx style headers. Both forms can be used inside a
+single document.
 
 ### Setext Style
 
@@ -231,56 +202,14 @@ the header text. For example:
 > Again, the original Markdown syntax allows one to omit the blank line before an atx style header.
 {: .markdown-difference}
 
-### 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, i.e. 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 until the first letter are removed.
-* Everything except letters and numbers is converted to dashes.
-* Everything is lowercased.
-* 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}
 
-### Manually Specifying a Header ID
+### Specifying a Header ID
 
-Additionally to automatic header ID generation, 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:
+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}
     -----
@@ -390,49 +319,6 @@ example:
 This type of code block is especially useful for copy-pasted code since you don't need to indent the
 code.
 
-### Showing Whitespace in a Code Block
-
-It is sometimes useful to visualize whitespace within a code block. This can be achieved in kramdown
-by adding the class `show-whitespaces` to a code block (using a [block
-IAL](#block-inline-attribute-lists)).
-
-Here is an example where the whitespaces are shown:
-
-    	  leading tab	and space
-    trailing   tab and space    	
-{: .show-whitespaces}
-
-
-### Automatic Syntax Highlighting   {#syntax-highlighting}
-
-kramdown supports syntax highlighting of code. Just add the key `lang` to a code block (using a
-[block IAL](#block-inline-attribute-lists)) and it will be highlighted using the specified language.
-Details on the supported languages can be found in the documentation for each converter.
-
-Here is an example on how Ruby code is highlighted:
-
-    require 'kramdown'
-
-    Kramdown::Document.new('* something').to_html
-    puts 1 + 1
-{: lang='ruby'}
-
-
-## 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:
-
-    * * *
-
-    ---
-
-      _  _  _  _
-
-    ---------------
-
 
 ## Lists
 
@@ -445,7 +331,8 @@ 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
+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
@@ -624,6 +511,14 @@ useful when the paragraph starts with something looking like a list item marker)
     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
 
@@ -820,6 +715,22 @@ editor. However, the table syntax is flexible and the above table could also be
     | 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]
@@ -1038,167 +949,8 @@ comments is not processed:
     continues here.
 
 
-## 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 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 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 defined 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}
-
-
-## 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
-
-:   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 built-in:
-
-`comment`
-
-:   Treats the body text as a comment which does not show in the output.
-
-`nomarkdown`
-
-:   The body is not processed with kramdown but output as-is.
 
-`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 enable 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.
-
-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
+# Text Markup
 
 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.
@@ -1481,6 +1233,39 @@ foot note definitions are ignored. If more than one footnote definitions have th
 name, all footnote definitions but the last are ignored.
 
 
+## 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 definition 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.
+
+Here are some examples:
+
+    This is some text not written in HTML but in another language!
+
+    *[another language]: It's called Markdown
+    *[HTML]: HyperTextMarkupLanguage
+
+> Abbreviation definitions are, despite being described here, block level elements.
+{: .information}
+
+
 ## Typographic Symbols
 
 > The original Markdown syntax does not support these transformations.
@@ -1501,7 +1286,149 @@ when kramdown falsely replace the quotes. If this is the case, just \'escape\" t
 won't be replaced with fancy ones.
 
 
-## Span Inline Attribute Lists
+
+# Other Markup
+
+This section describes markup that is not widely used in kramdown documents but which are sometimes
+needed nonetheless.
+
+
+## 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 necesary!
+
+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-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 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 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 defined 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.
+
+
+## Inline Attribute Lists
+
+These elements are used to attach attributes to another element.
+
+### 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 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
 
 > This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
 > the [Maruku] package.
@@ -1510,9 +1437,84 @@ won't be replaced with fancy ones.
 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
-to which it should be applied, no additional character is allowed between.
+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}.
+
+
+## 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:
+
+* an 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.
+
+`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}