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