Syntax | kramdown and Quick Reference | kramdown do a pretty good job of explaining what’s possible with Kramdown. This page documents a few extra things I’ve either found obscure or impossible (so that I don’t research them again!).
- Delete / Strike-through
- Abbreviations with brackets bug
- Blockquotes
- Code in lists / nested lists
- Tildes within code blocks
- Syntax highlighting
- Header attributes
- Tables
- Image links
- Linking to fragment identifiers
- References
Delete / Strike-through
Kramdown doesn’t have a shortcut for strike-through / deleted text. Use the HTML del tag:
<del>Deleted text</del>
Abbreviations with brackets bug
I’ve found a couple of situations where you can’t use an abbreviation that contains brackets. The abbreviation is defined somewhere as [(X)HTML]: (eXtensible) HyperText Markup Language. It doesn’t matter which type of bracket - parentheses, curly or square.
Using that abbreviation in the following locations won’t work:
-
As a link name:
[(X)HTML](http://en.wikipedia.org/wiki/Xhtml) won't work. -
At the beginning of a list:
* [(X)HTML] won't work.Though strangely it does work when not at the beginning of the list:
* Will work [(X)HTML].
Attempting these will cause an error:
NoMethodError: undefined method `empty?' for nil:NilClass
...
0. /usr/lib64/ruby/gems/1.8/gems/kramdown-0.13.3/lib/kramdown/converter/html.rb:323:in `convert_abbreviation'
I’ve been unable to work around this - not by escaping the brackets nor using HTML character codes.
I’ve filed a bug report.
Blockquotes
Blockquotes are odd. As far as I’m concerned they should escape all HTML and preserve the formatting of the text. But they don’t.
So, if you want line breaks be sure to add two spaces to the end of the line and be sure to escape any less-than signs to prevent them being interpreted as HTML. Generally, watch out for any kramdown processing of the blockquote’s contents.
Here’s an example showing how escaped less-than signs and newlines were necessary to maintain formatting in the blockquote (the underscores represent spaces):
> Sep 14 16:16:37 slap postfix/pickup[13599]: C4E3B744DDA: uid=1000 from=\<steph>__
> Sep 14 16:16:37 slap postfix/cleanup[13650]: C4E3B744DDA: message-id=\<20080914151637.GA13645@slap>__
> Sep 14 16:16:37 slap postfix/qmgr[13596]: C4E3B744DDA: from=\<steph@slap.localdomain>, size=386, nrcpt=1 (queue active)
Code in lists / nested lists
You can add kramdown code to a list (e.g. add a code block to an item or nest lists) but in order to do so you must maintain the list’s indentation - 2 spaces for a normal list (e.g. asterisk and space) and 3 for an ordered list (number, stop and space).
1. Item one, with code block
~~~
this code block has three spaces before it
~~~
This code block has seven (3+4) spaces before it
2. Item two
...
10. Item ten
~~~
This code block has four spaces before it
~~~
This code block has eight (4+4) spaces before it
If you don’t maintain the list’s indentation you will end up with multiple lists.
Tildes within code blocks
It seems that you can’t escape tildes in kramdown, so if you want to have tildes within a code block then you’ll have to add a space beforehand so that they’re not interpreted as the start/end of the code block.
~~~
~~~ These tildes have a space before them.
~~~
Syntax highlighting
~~~ # Output "I love Ruby" say = "I love Ruby" puts say ~~~ {:.language-ruby}
This will add syntax highlighting and line numbers to the code block.
# Output "I love Ruby" say = "I love Ruby" puts say
You don’t have use the tilda form, you can use the 4-spaces form instead:
say = "I love Ruby"
{:.language-ruby}
Syntax highlighting for inline code is not supported at the time of writing.
Header attributes
Settext style:
The header
----------
{: name="whatever"}
ATX style:
## The header
{: name="whatever"}
Note that Kramdown will automatically add an id attribute to headers, by making the header title lower case and replacing any spaces with hyphens:
Some Title -> some-title
This means you can easily link to any header via [Some Title](#some-title).
Tables
|----------------+----------------+----------------|
| Header 1 | Header 2 | Header 3 |
|----------------+----------------+----------------|
| Row 1 column 1 | Row 1 column 2 | Row 1 column 3 |
| Row 2 column 1 | Row 2 column 2 | Row 2 column 3 |
|----------------+----------------+----------------|
Tables are incredibly basic. For example, I couldn’t find a way of setting attributes on table headers or cells.
If you want to e.g. set a width on the first table header you could give the table a class:
|------+------|
| foo | bar |
|------+------|
| blah | blah |
|------+------|
{:.widetable}
Then style it using CSS:
table.widetable th:first-child { width: 10em; }
Neither do tables support multiline text, i.e. you can’t break the contents of a table cell across multiple lines, which to me rather defeats one point of using kramdown - your file won’t be easily readable in plain text when you have lots of data in a table cell.
Image links
[](web link)
Linking to fragment identifiers
To create a fragment identifier in your page, simple give a block level element an id attribute:
Some text fragment
{:#the-fragment-id}
Note that Kramdown will automatically add ID to headers, by making the header title lower case and replacing any spaces with hyphens:
Some Title -> some-title
Link to a fragment identifier anchor using a normal link:
[The link text](#the-fragment-id)
[Some Title](#some-title)
