Jason's Blog

A stochastic thought repository

Kramdown Support for Jekyll

| Comments

Update Dec. 9th 2010: Added some instructions on kramdown and Jekyll, (optionally with Coderay). Jump down to it.

Update Nov. 11th 2010: My changes have been merged into the mainline branch, which can be found on Github.

The last several months I’ve been fiddling around with different Markdown converters used with Jekyll. I like Maruku’s enhanced feature set (footnotes are nice), but was dissapointed with the execution speed. I briefly played around with Rdiscount, which is much faster, but I missed the extra features of Maruku.

I then discovered kramdown. It seems like a happy middle between Maruku and Rdiscount performance-wise, while containing a feature set even larger than that of Maruku. Unfortunately, it isn’t yet supported by Jekyll, though it had been a long requested feature.

I waited for a couple months, and then decided to fork Jekyll and add the functionality myself. At the time, I was unsure how to support options passed to kramdown’s HTML parser, so I left that part off to work on later.

Another coder apparently had the same idea as me at almost exactly the same time, and created his own fork with the same functionality, but also didn’t add the options passing.

With the start of Thanksgiving break, I’ve finally had some time to tack on the options functionality. It goes into the site configuration YAML file just like Maruku options or Rdiscount extensions would.

Hopefully, the fork will be pulled into the main branch, though I may need to clean up the options passing portion, it admittedly feels a bit hackish. I’m a n00b ruby coder, so my excuse is that I don’t know any better. Fixes or suggestions are welcome though.

Using kramdown and Jekyll

First, be sure you are using my branch of Jekyll (or v0.8.0 or higher in the mainline).

To use kramdown with Jekyll, you will need the following in your _config.yml file.

1
2
3
...
markdown: kramdown
...

See the Jekyll wiki configuration page for more of the options.

Adding Coderay

If you are wanting to additionally use Coderay for codeblocking, then your _config.yml file must include the following.

1
2
3
4
5
...
markdown: kramdown
kramdown:
  use_coderay: true
...

You may use a kramdown block attribute within your markdown files to specify how you want Coderay to handle the codeblocking for that block.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
layout: default
title: Silly Test Post
---

This is a paragraph element before a codeblocked block of C code.

    int main(void) {
        printf("Hello world!");
        return 0;
    }
{:lang="c"}

Another paragraph element.

Comments