# kramdown Syntax

This is version 2.3.1 of the syntax documentation.

The kramdown syntax is based on the Markdown syntax and has been enhanced with features that are found in other Markdown implementations like Maruku, PHP Markdown Extra and Pandoc. However, it strives to provide a strict syntax with definite rules and therefore isn’t completely compatible with Markdown. Nonetheless, most Markdown documents should work fine when parsed with kramdown. All places where the kramdown syntax differs from the Markdown syntax are highlighted.

Following is the complete syntax definition for all elements kramdown supports. Together with the documentation on the available converters, it is clearly specified what you will get when a kramdown document is converted.

## Source Text Formatting

A kramdown document may be in any encoding, for example ASCII, UTF-8 or ISO-8859-1, and the output will have the same encoding as the source.

The document consists of two types of elements, block-level elements and span-level elements:

• Block-level elements define the main structure of the content, for example, what part of the text should be a paragraph, a list, a blockquote and so on.

• Span-level elements mark up small text parts as, for example, emphasized text or a link.

Thus span-level elements can only occur inside block-level elements or other span-level elements.

You will often find references to the “first column” or “first character” of a line in a block-level element descriptions. Such a reference is always to be taken relative to the current indentation level because some block-level elements open up a new indentation level (e.g. blockquotes). The beginning of a kramdown document opens up the default indentation level which begins at the first column of the text.

### Line Wrapping

Some lightweight markup syntax don’t work well in environments where lines are hard-wrapped. For example, this is the case with many email programs. Therefore kramdown allows content like paragraphs or blockquotes to be hard-wrapped, i.e. broken across lines. This is sometimes referred to as “lazy syntax” since the indentation or line prefix required for the first line of content is not required for the consecutive lines.

Block-level elements that support line wrapping always end when one of the following conditions is met:

Line wrapping is allowed throughout a kramdown document but there are some block-level elements that do not support being hard-wrapped:

This is not an issue in most situations since headers normally fit on one line. If a header text gets too long for one line, you need to use HTML syntax instead.

fenced code blocks

The delimiting lines of a fenced code block do not support hard-wrapping. Since everything between the delimiting lines is taken as is, the content of a fenced code block does also not support hard-wrapping.

definition list terms

Each definition term has to appear on a separate line. Hard-wrapping would therefore introduce additional definition terms. The definitions themselves, however, do support hard-wrapping.

tables

Since each line of a kramdown table describes one table row or a separator, it is not possible to hard-wrap tables.

Note that it is NOT recommended to use lazy syntax to write a kramdown document. The flexibility that the kramdown syntax offers due to the issue of line wrapping hinders readability and should therefore not be used.

### Usage of Tabs

kramdown assumes that tab stops are set at multiples of four. This is especially important when using tabs for indentation in lists. Also, tabs may only be used at the beginning of a line when indenting text and must not be preceded by spaces. Otherwise the results may be unexpected.

### Automatic and Manual Escaping

Depending on the output format, there are often characters that need special treatment. For example, when converting a kramdown document to HTML one needs to take care of the characters <, > and &. To ease working with these special characters, they are automatically and correctly escaped depending on the output format.

This means, for example, that you can just use <, > and & in a kramdown document and need not think about when to use their HTML entity counterparts. However, if you do use HTML entities or HTML tags which use one of the characters, the result will be correct nonetheless!

Since kramdown also uses some characters to mark-up the text, there needs to be a way to escape these special characters so that they can have their normal meaning. This can be done by using backslash escapes. For example, you can use a literal back tick like this:

This \is not a code\ span!

Following is a list of all the characters (character sequences) that can be escaped:

\         backslash
.         period
*         asterisk
_         underscore
+         plus
-         minus
=         equal sign
         back tick
()[]{}<>  left and right parens/brackets/braces/angle brackets
#         hash
!         bang
<<        left guillemet
>>        right guillemet
:         colon
|         pipe
"         double quote
'         single quote

## HTML Blocks

The original Markdown syntax specifies that an HTML block must start at the left margin, i.e. no indentation is allowed. Also, the HTML block has to be surrounded by blank lines. Both restrictions are lifted for kramdown documents. Additionally, the original syntax does not allow you to use Markdown syntax in HTML blocks which is allowed with kramdown.

An HTML block is potentially started if a line is encountered that begins with a non-span-level HTML tag or a general XML tag (opening or closing) which may be indented up to three spaces.

The following HTML tags count as span-level HTML tags and won’t start an HTML block if found at the beginning of an HTML block line:

a abbr acronym b big bdo br button cite code del dfn em i img input
ins kbd label option q rb rbc rp rt rtc ruby samp select small span
strong sub sup textarea tt var

Further parsing of a found start tag depends on the tag and in which of three possible ways its content is parsed:

• Parse as raw HTML block: If the HTML/XML tag content should be handled as raw HTML, then only HTML/XML tags are parsed from this point onwards and text is handled as raw, unparsed text until the matching end tag is found or until the end of the document. Each found tag will be parsed as raw HTML again. However, if a tag has a markdown attribute, this attribute controls parsing of this one tag (see below).

Note that the parser basically supports only correct XHTML! However, there are some exceptions. For example, attributes without values (i.e. boolean attributes) as well as unquoted attribute values are also supported and elements without content like <hr /> can be written as <hr>. If an invalid closing tag is found, it is ignored.

• Parse as block-level elements: If the HTML/XML tag content should be parsed as text containing block-level elements, the remaining text on the line will be parsed by the block-level parser as if it appears on a separate line (Caution: This also means that if the line consists of the start tag, text and the end tag, the end tag will not be found!). All following lines are parsed as block-level elements until an HTML block line with the matching end tag is found or until the end of the document.

• Parse as span-level elements: If the HTML/XML tag content should be parsed as text containing span level elements, then all text until the next matching end tag or until the end of the document will be the content of the tag and will later be parsed by the span-level parser. This also means that if the matching end tag is inside what appears to be a code span, it is still used!

If there is text after an end tag, it will be parsed as if it appears on a separate line except when inside a raw HTML block.

Also, if an invalid closing tag is found, it is ignored.

Note that all HTML tag and attribute names are converted to lowercase!

By default, kramdown parses all block HTML tags and all XML tags as raw HTML blocks. However, this can be configured with the parse_block_html. If this is set to true, then syntax parsing in HTML blocks is globally enabled. It is also possible to enable/disable syntax parsing on a tag per tag basis using the markdown attribute:

• If an HTML tag has an attribute markdown="0", then the tag is parsed as raw HTML block.

• If an HTML tag has an attribute markdown="1", then the default mechanism for parsing syntax in this tag is used.

• If an HTML tag has an attribute markdown="block", then the content of the tag is parsed as block level elements.

• If an HTML tag has an attribute markdown="span", then the content of the tag is parsed as span level elements.

The following list shows which HTML tags are parsed in which mode by default when markdown="1" is applied or parse_block_html is true:

Parse as raw HTML
script style math option textarea pre code kbd samp var

Also, all general XML tags are parsed as raw HTML blocks.

Parse as block-level elements
applet button blockquote body colgroup dd div dl fieldset form iframe li
map noscript object ol table tbody thead tfoot tr td ul
Parse as span-level elements
a abbr acronym address b bdo big cite caption code del dfn dt em
h1 h2 h3 h4 h5 h6 i ins kbd label legend optgroup p pre q rb rbc
rp rt rtc ruby samp select small span strong sub sup th tt var

Remember that all span-level HTML tags like a or b do not start an HTML block! However, the above lists also include span-level HTML tags in the case the markdown attribute is used on a tag inside a raw HTML block.

Here is a simple example input and its HTML output with parse_block_html set to false:

This is a para.
<div>
Something in here.
</div>
Other para.
<p>This is a para.</p>
<div>
Something in here.
</div>
<p>Other para.</p>

As one can see the content of the div tag will be parsed as raw HTML block and left alone. However, if the markdown="1" attribute was used on the div tag, the content would be parsed as block-level elements and therefore converted to a paragraph.

You can also use several HTML tags at once:

<div id="content"><div id="layers"><div id="layer1">
This is some text in the layer1 div.
</div>
This is some text in the layers div.
</div></div>
This is a para outside the HTML block.

However, remember that if the content of a tag is parsed as block-level elements, the content that appears after a start/end tag but on the same line, is processed as if it appears on a new line:

<div markdown="1">This is the first part of a para,
which is continued here.
</div>

<p markdown="1">This works without problems because it is parsed as
span-level elements</p>

this line is parsed as a paragraph</div>

Since setting parse_block_html to true can lead to some not wanted behaviour, it is generally better to selectively enable or disable block/span-level elements parsing by using the markdown attribute!

Unclosed block-level HTML tags are correctly closed at the end of the document to ensure correct nesting and invalidly used end tags are removed from the output:

This is a para.
<div markdown="1">
Another para.
</p>
<p>This is a para.</p>
<div>
<p>Another para.</p>
</div>

The parsing of XML comments is also supported. The content of XML comments may span multiple lines. The start of an XML comment may only appear at the beginning of a line, optionally indented up to three spaces. If there is text after the end of an XML comment, it will be parsed as if it appears on a separate line. kramdown syntax in XML comments is not processed:

This is a para.
<!-- a *comment* -->
<!-- a comment
spanning multiple lines
--> First part of para,
continues here.

# Text Markup

These elements are all span-level elements and used inside block-level elements to markup text fragments. For example, one can easily create links or apply emphasis to certain text parts.

Note that empty span-level elements are not converted to empty HTML tags but are copied as-is to the output.

This is the easiest one to create: Just surround a web address or an email address with angle brackets and the address will be turned into a proper link. The address will be used as link target and as link text. For example:

Information can be found on the <http://example.com> homepage.
You can also mail me: <me.example@example.com>

It is not possible to specify a different link text using automatic links – use the other link types for this!

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.

Notes:

• The link text is treated like normal span-level text and therefore is parsed and converted. However, if you use square brackets within the link text, you have to either properly nest them or to escape them. It is not possible to create nested links!

The link text may also be omitted, e.g. for creating link anchors.

• The link URL has to contain properly nested parentheses if no title is specified, or the link URL must be contained in angle brackets (incorrectly nested parentheses are allowed).

• The link title may not contain its delimiters and may not be empty.

To create a reference style link, you need to surround the link text with square brackets (as with inline links), followed by optional spaces/tabs/line breaks and then optionally followed with another set of square brackets with the link identifier in them. A link identifier may not contain a closing bracket and, when specified in a link definition, newline characters; it is also not case sensitive, line breaks and tabs are converted to spaces and multiple spaces are compressed into one. For example:

If you don’t specify a link identifier (i.e. only use empty square brackets) or completely omit the second pair of square brackets, the link text is converted to a valid link identifier by removing all invalid characters and inserting spaces for line breaks. If there is a link definition found for the link identifier, a link will be created. Otherwise the text is not converted to a link.

The link definition can be put anywhere in the document. It does not appear in the output. A link definition looks like this:

Link definitions are, despite being described here, non-content block-level elements.

The link definition has the following structure:

• The link identifier in square brackets, optionally indented up to three spaces,
• then a colon and one or more optional spaces/tabs,
• then the link URL which must contain at least one non-space character, or a left angle bracket, the link URL and a right angle bracket,
• then optionally the title in single or double quotes, separated from the link URL by one or more spaces or on the next line by itself indented any number of spaces/tabs.

The original Markdown syntax also allowed the title to be specified in parenthesis. This is not allowed for consistency with the inline title.

If you have some text that looks like a link definition but should really be a link and some text, you can escape the colon after the link identifier:

The next paragraph contains a link and some text.

[Room 100]\: There you should find everything you need!

Although link definitions are non-content block-level elements, block IALs can be used on them to specify additional attributes for the links:

{:hreflang="de"}

### Images

Images can be specified via a syntax that is similar to the one used by links. The difference is that you have to use an exclamation mark before the first square bracket and that the link text of a normal link becomes the alternative text of the image link. As with normal links, image links can be written inline or reference style. For example:

Here comes a ![smiley](../images/smiley.png)! And here
![too](../images/other.png 'Title text'). Or ![here].
With empty alt text ![](see.jpg)

The link definition for images is exactly the same as the link definition for normal links. Since additional attributes can be added via span and block IALs, it is possible, for example, to specify image width and height:

Here is an inline ![smiley](smiley.png){:height="36px" width="36px"}.

And here is a referenced ![smile]

[smile]: smile.png
{: height="36px" width="36px"}

## Emphasis

kramdown supports two types of emphasis: light and strong emphasis. Text parts that are surrounded with single asterisks * or underscores _ are treated as text with light emphasis, text parts surrounded with two asterisks or underscores are treated as text with strong emphasis. Surrounded means that the starting delimiter must not be followed by a space and that the stopping delimiter must not be preceded by a space.

Here is an example for text with light and strong emphasis:

*some text*
_some text_
**some text**
__some text__

The asterisk form is also allowed within a single word:

This is un*believe*able! This d_oe_s not work!

Text can be marked up with both light and strong emphasis, possibly using different delimiters. However, it is not possible to nest strong within strong or light within light emphasized text:

This is a ***text with light and strong emphasis***.
This **is _emphasized_ as well**.
This *does _not_ work*.
This **does __not__ work either**.

If one or two asterisks or underscores are surrounded by spaces, they are treated literally. If you want to force the literal meaning of an asterisk or an underscore you can backslash-escape it:

This is a * literal asterisk.
These are ** two literal asterisk.
As \*are\* these!

## Code Spans

This is the span-level equivalent of the code block element. You can markup a text part as code span by surrounding it with backticks . For example:

Use <html> tags for this.

Note that all special characters in a code span are treated correctly. For example, when a code span is converted to HTML, the characters <, > and & are substituted by their respective HTML counterparts.

To include a literal backtick in a code span, you need to use two or more backticks as delimiters. You can insert one optional space after the starting and before the ending delimiter (these spaces are not used in the output). For example:

Here is a literal    backtick.
And here is   some   text (note the two spaces so that one is left
in the output!).

A single backtick surrounded by spaces is treated as literal backtick. If you want to force the literal meaning of a backtick you can backslash-escape it:

This is a  literal backtick.
As \are\ these!

As with code blocks you can set the language of a code span by using an IAL:

This is a Ruby code fragment x = Class.new{:.language-ruby}

## HTML Spans

HTML tags cannot only be used on the block-level but also on the span-level. Span-level HTML tags can only be used inside one block-level element, it is not possible to use a start tag in one block level element and the end tag in another. Note that only correct XHTML is supported! This means that you have to use, for example, <br /> instead of <br> (although kramdown tries to fix such errors if possible).

By default, kramdown parses kramdown syntax inside span HTML tags. However, this behaviour can be configured with the parse_span_html option. If this is set to true, then syntax parsing in HTML spans is enabled, if it is set to false, parsing is disabled. It is also possible to enable/disable syntax parsing on a tag per tag basis using the markdown attribute:

• If an HTML tag has an attribute markdown="0", then no parsing (except parsing of HTML span tags) is done inside that HTML tag.

• If an HTML tag has an attribute markdown="1", then the content of the tag is parsed as span level elements.

• If an HTML tag has an attribute markdown="block", then a warning is issued because HTML spans cannot contain block-level elements and the attribute is ignored.

• If an HTML tag has an attribute markdown="span", then the content of the tag is parsed as span level elements.

The content of a span-level HTML tag is normally parsed as span-level elements. Note, however, that some tags like <script> are not parsed, i.e. their content is not modified.

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 XML comments as well as general span-level HTML and XML tags have to be preceded by at least one non whitespace character on the same line so that kramdown correctly recognizes them as span-level element and not as block-level element. However, all span HTML tags, i.e. a, em, b, …, (opening or closing) can appear at the start of a line.

Unclosed span-level HTML tags are correctly closed at the end of the span-level text to ensure correct nesting and invalidly used end tags or block HTML tags are removed from the output:

This is </invalid>.

This <span>is automatically closed.
<p>This is .</p>

<p>This <span>is automatically closed.</span></p>

Also note that one or more consecutive new line characters in an HTML span tag are replaced by a single space, for example:

## Footnotes

This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from the PHP Markdown Extra package.

Footnotes in kramdown are similar to reference style links and link definitions. You need to place the footnote marker in the correct position in the text and the actual footnote content can be defined anywhere in the document.

More exactly, a footnote marker can be created by placing the footnote name in square brackets. The footnote name has to start with a caret (^), followed by a word character or a digit and then optionally followed by other word characters, digits or dashes. For example:

This is some text.[^1]. Other text.[^footnote].

Note that footnote markers cannot be used as part of the link text of a link because this would lead to nested links which is not allowed in HTML.

Footnote markers with the same name will link to the same footnote definition. The actual naming of a footnote does not matter since the numbering of footnotes is controlled via the position of the footnote markers in the document (the first found footnote marker will get the number 1, the second new footnote marker the number 2 and so on). If there is a footnote definition found for the identifier, a footnote will be created. Otherwise the footnote marker is not converted to a footnote link. Also note that all attributes set via a span IAL are ignored for a footnote marker!

A footnote definition is used to define the content of a footnote and has the following structure:

• The footnote name in square brackets, optionally indented up to three spaces,
• then a colon and one or more optional spaces,
• then the text of the footnote
• and optionally more text on the following lines which have to follow the syntax for standard code blocks (the leading four spaces/one tab are naturally stripped from the text)

Footnote definitions are, despite being described here, non-content block-level elements.

The whole footnote content is treated like block-level text and can therefore contain any valid block-level element (also, any block-level element can be the first element). If you want to have a code block as first element, note that all leading spaces/tabs on the first line are stripped away. Here are some example footnote definitions:

[^1]: Some *crazy* footnote definition.

[^footnote]:
> Blockquotes can be in a footnote.

as well as code blocks

or, naturally, simple paragraphs.

[^other-note]:       no code block here (spaces are stripped away)

[^codeblock-note]:
this is now a code block (8 spaces indentation)

It does not matter where you put a footnote definition in a kramdown document; the content of all referenced footnote definitions will be placed at the end of the kramdown document. Not referenced footnote definitions are ignored. If more than one footnote definitions have the same footnote name, all footnote definitions but the last are ignored.

Although footnote definitions are non-content block-level elements, block IALs can be used on them to attach attributes. How these attributes are used depends on the converter.

## Abbreviations

This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from the PHP Markdown Extra package.

kramdown provides a syntax to assign the full phrase to an abbreviation. When writing the text, you don’t need to do anything special. However, once you add abbreviation definitions, the abbreviations in the text get marked up automatically. Abbreviations can consist of any character except a closing bracket.

An abbreviation definition is used to define the full phrase for an abbreviation and has the following structure:

• An asterisk and the abbreviation in square brackets, optionally indented up to three spaces,
• then a colon and the full phrase of the abbreviation on one line (leading and trailing spaces are stripped from the full phrase).

Later abbreviation definitions for the same abbreviation override prior ones and it does not matter where you put an abbreviation definition in a kramdown document. Empty definitions are also allowed.

Although abbreviation definitions are non-content block-level elements, block IALs can be used on them to specify additional attributes.

Here are some examples:

This is some text not written in HTML but in another language!

*[another language]: It's called Markdown

*[HTML]: HyperTextMarkupLanguage
{:.mega-big}

Abbreviation definitions are, despite being described here, non-content block-level elements.

## Typographic Symbols

The original Markdown syntax does not support these transformations.

kramdown converts the following plain ASCII character into their corresponding typographic symbols:

• --- will become an em-dash (like this —)
• -- will become an en-dash (like this –)
• ... will become an ellipsis (like this …)
• << will become a left guillemet (like this «) – an optional following space will become a non-breakable space
• >> will become a right guillemet (like this ») – an optional leading space will become a non-breakable space

The parser also replaces normal single ' and double quotes " with “fancy quotes”. There may be times when kramdown falsely replace the quotes. If this is the case, just \'escape\" the quotes and they won’t be replaced with fancy ones.

# Non-content elements

This section describes the non-content elements that are used in kramdown documents, i.e. elements that don’t provide content for the document but have other uses such as separating block-level elements or attaching attributes to elements.

Three non-content block-level elements are not described here because they fit better where they are:

## End-Of-Block Marker

The EOB marker is not part of the standard Markdown syntax.

The End-Of-Block (EOB) marker – a ^ as first character on an otherwise empty line – is a block level element that can be used to specify the end of a block-level element even if the block-level element, after which it is used, would continue otherwise. If there is no block-level element to end, the EOB marker is simply ignored.

You won’t find an EOB marker in most kramdown documents but sometimes it is necessary to use it to achieve the wanted results which would be impossible otherwise. However, it should only be used when absolutely necessary!

For example, the following gives you one list with two items:

* list item one

* list item two

By using an EOB marker, you can make two lists with one item each:

* list one
^
* list two

## Attribute List Definitions

This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from the Maruku package.

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 is used to attach attributes to a block-level element and the Span Inline Attribute List is used to attach attributes to a span-level element.

Following are some examples of attribute list definitions (ALDs) and afterwards comes the syntax explanation:

{:ref-name: #myid .my-class}
{:other: ref-name #id-of-other title="hallo you"}
{:test: key="value \" with quote" and other='quote brace \}'}

An ALD line has the following structure:

• a left brace, optionally preceded by up to three spaces,
• followed by a colon, the reference name and another colon,
• followed by attribute definitions (allowed characters are backslash-escaped closing braces or any character except a not escaped closing brace),
• followed by a closing brace and optional spaces until the end of the line.

The reference name needs to start with a word character or a digit, optionally followed by other word characters, digits or dashes.

There are four different types of attribute definitions which have to be separated by one or more spaces:

references

This must be a valid reference name. It is used to reference an other ALD so that the attributes of the other ALD are also included in this one. The reference name is ignored when collecting the attributes if no attribute definition list with this reference name exists. For example, a simple reference looks like id.

key-value pairs

A key-value pair is defined by a key name, which must follow the rules for reference names, then an equal sign and then the value in single or double quotes. If you need to use the value delimiter (a single or a double quote) inside the value, you need to escape it with a backslash. Key-value pairs can be used to specify arbitrary attributes for block or span-level elements. For example, a key-value pair looks like key1="bef \"quoted\" aft" or title='This is a title'.

ID name

An ID name is defined by using a hash and then the identifier name which needs to start with an ASCII alphabetic character (A-Z or a-z), optionally followed by other ASCII characters, digits, dashes or colons. This is a short hand for the key-value pair id="IDNAME" since this is often used. The ID name specifies the unique ID of a block or span-level element. For example, an ID name looks like #myid.

class names

A class name is defined by using a dot and then the class name which may contain any character except whitespace, the dot character and the hash character.

This is (almost, but not quite) a short hand for the key-value pair class="class-name". Almost because it actually means that the class name should be appended to the current value of the class attribute. The following ALDs are all equivalent:

{:id: .cls1 .cls2}
{:id: class="cls1" .cls2}
{:id: class="something" class="cls1" .cls2}
{:id: class="cls1 cls2"}

As can be seen from the example of the class names, attributes that are defined earlier are overwritten by ones with the same name defined later.

Also, everything in the attribute definitions part that does not match one of the above four types is ignored.

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.

This block-level element is used to attach attributes to another block-level element. A block inline attribute list (block IAL) has the same structure as an ALD 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.

This is a version of the block inline attribute list for span-level elements. It has the same structure as the block IAL except that leading and trailing spaces are not allowed. A span IAL (or two or more span IALs) has to be put directly after the span-level element to which it should be applied, no additional character is allowed between, otherwise it is ignored and only removed from the output.

Here are some examples for span IALs:

This *is*{:.underline} some code{:#id}{:.class}.

The special span IAL {::} contains no attributes but doesn’t generate a warning either. It can be used to separate consecutive elements that would be falsely parsed if not separated. Here is an use case:

This *is italic*{::}*marked*{:.special} text

## Extensions

This syntax feature is not part of the original Markdown syntax.

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. Here are some examples of how to specify extensions and afterwards is the syntax definition:

{::comment}
This text is completely ignored by kramdown - a comment in the text.
{:/comment}

Do you see {::comment}this text{:/comment}?
{::comment}some other comment{:/}

{::options key="val" /}

An extension can be specified with or without a body. Therefore there exist a start and an end tag for extensions. The start tag has the following structure:

• a left brace,
• followed by two colons and the extension name,
• optionally followed by a space and attribute definitions (allowed characters are backslash-escaped closing braces or any character except a not escaped closing brace – same as with ALDs),
• followed by a slash and a right brace (in case the extension has no body) or only a right brace (in case the extension has a body).

The stop tag has the following structure:

• a left brace,
• followed by a colon and a slash,
• optionally followed by the extension name,
• followed by a right brace.

A stop tag is only needed if the extension has a body!

The above syntax can be used as is for span-level extensions. The starting and ending lines for block-level extensions are defined as:

• The starting line consists of the extension start tag, optionally preceded by up to three spaces, and followed by optional spaces until the end of the line.
• The ending line consists of the extension stop tag, optionally preceded by up to three spaces, and followed by optional spaces until the end of the line.

If no end tag can be found for an extension start tag, the start tag is treated as if it has no body. If an invalid extension stop tag is found, it is ignored. If an invalid extension name is specified the extension (and the eventually specified body) are ignored.

The following extensions can be used with kramdown:

comment

Treat the body text as a comment which does not show in the output.

nomarkdown

Don’t process the body with kramdown but output it as-is. The attribute type specifies which converters should output the body: if the attribute is missing, all converters should output it. Otherwise the attribute value has to be a space separated list of converter names and these converters should output the body.

options

Should be used without a body since the body is ignored. Is used for setting the global options for the kramdown processor (for example, to disable automatic header ID generation). Note that options that are used by the parser are immediately effective whereas all other options are not! This means, for example, that it is not possible to set converter options only for some part of a kramdown document.