Search results

Updating from redcarpet and Pygments to Kramdown and Rouge on Github Pages

by Tom Johnson on Feb 21, 2016
categories: jekyll

Github Pages is a sweet service that builds your Jekyll site for you when you commit changes to a Github repo. If you were using redcarpet and Pygments, you now should switch to Kramdown and Rouge to stay updated with the recommended Markdown filter and syntax highlighter supported by Github Pages. Switching to Kramdown requires you to both update your configuration file and usually use 3 spaces when inserting code blocks within list items instead of 4.

Updates to Markdown filter and syntax highlighters

I use Github Pages to publish content for my Jekyll-based blog, and I’ve also used it for authoring tech docs with Jekyll. When you commit changes to your Jekyll site stored in a Github repo, Github Pages will automatically perform the process of building the Jekyll site for you.

Jekyll processes HTML from Markdown using the Markdown processor that you specify in your configuration file. Github recently adopted Kramdown as their only Markdown processor, which will go into effect after May 1. redcarpet is the Markdown processor I was using. redcarpet will no longer be supported by Github Pages.

Additionally, a plugin for processing code blocks with syntax highlighting also changed. Instead of Pygments, Rouge will now be the only syntax highlighter supported by Github Pages. Github announced these changes in a recent blog post:

GitHub Pages now only supports Rouge, a pure-Ruby syntax highlighter, meaning you no longer need to install Python and Pygments to preview your site locally. If you were previously using Pygments for highlighting, the two libraries are feature compatible, so we’ll swap Rouge in for Pygments when we build your site, to ensure a seamless transition.

Traditionally, highlighting in Jekyll has been implemented via the {% highlight %} Liquid tag, forcing you to leave a pure-Markdown experience. With the kramdown and Rouge as the new defaults, syntax highlighting on GitHub Pages should work like you’d expect it to work anywhere else on GitHub, with native support for backtick-style fenced code blocks right within the Markdown.

How to make the updates to use Kramdown and Rouge

If you were using redcarpet and Pygments, and you want to switch to Kramdown and Rouge, you need to make an update in your configuration file. For example, if you previously had this:

highlighter: pygments
markdown: redcarpet
redcarpet:
  extensions: ["no_intra_emphasis", "fenced_code_blocks", "tables", "with_toc_data"]

Just change it to this:

highlighter: rouge
markdown: kramdown
kramdown:
  input: GFM
  auto_ids: true
  syntax_highlighter: rouge

Make sure you specify the Github Flavored Markdown parser by adding input: GFM. Otherwise backticks won’t be processed.

Follow Kramdown’s indentation syntax for code blocks within lists

With Github-flavored Markdown, when you insert a code block within a list, you can indent the code block 4 spaces.

But with Kramdown, you must line up the indent of the code block with the first non-space character after the list item marker (e.g., 1.). Usually this will mean indenting the code block 3 spaces instead of 4.

Thomas Leitner, the developer leading Kramdown, explains it as follows:

The gist is that the indentation for the list contents is determined by the column number of the first non-space character after the list item marker.

Examples (edit: I replaced the leading spaces with underscores so it looks correct):

*_some text -> 2 spaces indentation

*___some text -> 4 spaces indentation

1._some text -> 3 spaces indentation

If you have 4 spaces instead of 3, Kramdown will set off the code with code tags instead of pre tags. This will make a huge difference, since code tags render inline whereas pre renders as a div block.

A Kramdown/Rouge test

As a test, I published a sample Jekyll site here built by Github Pages that contains the Kramdown/Rouge configuration. The page has code blocks both inside and outside of list items.

The repo is here – kramdowntest – if you want to clone it and play around with it.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2024 Tom Johnson