| --- |
| 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 ![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](#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]. |
| |
| 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} |