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
- Bugs
- 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 do not escape HTML nor preserve the formatting of the text. You can use <pre>...</pre> tags for that.
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):
> Must escape certain characters like \<left angle brackets> that could be interpreted as HTML
> and add two spaces to the end of the line to get a line break. So far we have these spaces.
> This line does not have spaces
> so we do not get a newline.
Results in…
Must escape certain characters like <left angle brackets> that could be interpreted as HTML
and add two spaces to the end of the line to get a line break. So far we have these spaces.
This line does not have spaces so we do not get a newline.
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
Kramdown uses coderay by default for syntax highlighting.
Set the language-[lang] class on any code blocks:
~~~
# Output "I love Ruby"
say = "I love Ruby"
puts say
~~~
{:.language-ruby}
Or use this shortcut:
~~~ ruby
# Output "I love Ruby"
say = "I love Ruby"
puts say
~~~
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 block 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. Nor can Coderay highlight perl code :-/
Also see my Nanoc notes for info on setting up syntax highlighting in Kramdown (via Nanoc Rules config).
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 |
|----------------+----------------+----------------|
Or
|--------------------------------------------------|
| 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 |
|--------------------------------------------------|
There are many ways to write tables in kramdown, because lines delimit rows and pipes delimit columns and it ignores most else. Here’s the most basic way:
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 3 column 3
Tables are incredibly basic. While there are plenty of ways to write them, they can only contain basic data.
Table attributes
I couldn’t find a way of setting attributes on table headers or cells.
However you can set attributes on the table as a whole. So 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; }
Multiple lines
Nope. Tables don’t support multiline text i.e. you can’t break the contents of a table cell across multiple lines, whether you want multiple lines in your rendered table or in your file (to be rendered as a single line). The latter 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)
Bugs
3 or 5 character h2 breaks following heading
When you have a 3 or 5 character h2 tag in setext style immediately followed by another heading, something odd happens when the h2 is 3 or 5 characters long and the following heading won’t be interpreted as a heading.
Try this code and you’ll see the problem (you can see it on my test page):
123
---
### This should be a h3 but it is not :-(
1234
----
### This should be a h3 and it is :-)
12345
-----
### This should be a h3 but it is not :-(
123456
------
### This should be a h3 and it is :-)
Add an extra hyphen to fix:
123
----
### This should be a h3 and it is :-)
3 or 5 character h2 in code block causes missing newline
When you have a 3 or 5 character h2 tag in a code block you can lose the following line break.
123
---
There should be a line break above this line but there is not :-(
1234
----
There should be a line break above this line and there is :-)
12345
-----
There should be a line break above this line but there is not :-(
123456
------
There should be a line break above this line and there is :-)
It works fine if defining the code block with spaces instead of tildas (as I did in 3 or 5 character h2 breaks following heading above!
