As I wanted to move the blog to github-pages I also wanted to use the same type of markdown that github uses for its pages, project pages, wikis etc. Believe me at first I thought: “if I use jekyll surely I will have the same markdown as github”, and of course I couldn’t be more wrong.
So what exactly is Github Flavored Markdown, often called GFM? Its just normal markdown but with additional capabilities:
_ won’t be changed into italics.liquid syntax to create a code block- and |If you are looking for examples of those capabilities you need to visit their wiki page.
You can imagine that I wanted that and I also wanted to have a table of contents which happened to be the most troublesome thing in markdown. By a table of contents or TOC I mean auto generated links to headings like <h1> or <h2> in the article.
Jekyll supports several markdown “interpreters”, I’ve tried those:
There is also one called maruku but is currently deprecated and you can read on github-pages to migrate from using it.
I’ve tried those kramdown settings:
# Build settings
markdown: kramdown
kramdown:
auto_ids: true
input: GFM
toc_levels: 1..6
smart_quotes: lsquo,rsquo,ldquo,rdquo
use_coderay: false
The input option is set to GFM which was supposed to turn on Github Flavored Markdown, unfortunately it didn’t or lets say it did this partially. It was missing:
To get syntax highlighting in kramdown a liquid notation needs to be used like this: {% highlight ruby %}.
Then I tried rdiscount:
# Build settings
markdown: rdiscount
rdiscount:
extensions: ["autolink", "footnotes", "generate_toc", "smart"]
toc_token: "[TOC]"
There were few problems:
[^1] although promised on the project siteAt least table of contents worked but not without some trouble. Although I added generate_toc on the extensions list it didn’t appear with the keyword [TOC] that github was using. It seems you need to explicitly specify the keyword with the toc_token and believe me it was hard to find.
The last one I’ve checked was redcarpet, its supposed to be the best suited for me as github is working on it and deploying it on their machines.
# Build settings
markdown: redcarpet
markdown_ext: markdown,mkdown,mkdn,mkd,md
redcarpet:
extensions: ["tables", "autolink", "strikethrough", "space_after_headers", "with_toc_data", "fenced_code_blocks"]
And comparing to the previous two, redcarpet was a jackpot. Fenced code blocks were working, syntax highlighting also. Tables were correctly created, links were auto changed into <a href>. Everything worked except the mentioned table of contents. You probably noticed the with_toc_data on the extensions list, the problem is that it doesn’t work because its a renderer option. Currently Jekyll doesn’t support renderer options thats one thing, second is that github-pages don’t support custom Jekyll plugins so you can’t write anything in ruby yourself to get a TOC.
From all my desired features TOC is the one I can live without because I can always create it manually. I hope this article helps you with your blogs.