Syntax highlighting with Jekyll

Github pages support source code syntax highlighting by the gem Rouge, which can improve the readability of code snippets in a blog or page. Rouge has been the default highlighter for Jekyll since version 3. The following steps explains how you can add syntax highlighting to your Github / Jekyll site with Rouge.

Step 1: Integrate the gems Kramdown and Rouge

If you have not already done so, you can install the ruby gems Kramdown and Rouge locally with just one command (in Github they are enabled by default):

gem install kramdown rouge

Step 2: Configure

The following settings should be made in the configuration file _config.yml:

markdown: kramdown
highlighter: rouge

kramdown:
  input: GFM
  syntax_highlighter: rouge

Step 3: Determine the style

With the cli tool rougify as part of Rouge you can list all supported syntax highlighting themes:

rougify help style

Output:

>rougify help style
usage: rougify style [<theme-name>] [<options>]

Print CSS styles for the given theme.  Extra options are
passed to the theme.  Theme defaults to thankful_eyes.

options:
  --scope       (default: .highlight) a css selector to scope by

available themes:
  base16, base16.dark, base16.light, base16.monokai, 
  base16.monokai.dark, base16.monokai.light, base16.solarized, 
  base16.solarized.dark, base16.solarized.light, colorful, 
  github, gruvbox, gruvbox.dark, gruvbox.light, igorpro, 
  molokai, monokai, monokai.sublime, thankful_eyes, tulip

For my pages I use the theme github.

The appropriate stylesheet file /assets/css/syntax.css was generated by the following command:

rougify style github > assets/css/syntax.css

This stylesheet file has to be integrated into the Jekyll templates centrally - in my pages this is the template file /_includes/head.html:

<head>
    ...
  <link rel="stylesheet" href="/assets/css/syntax.css" />
</head>

Step 4: Mark the code snippets with the desired highlighter

To enable syntax highlighting for the code snippets in articles / pages, you have to mark them with the desired higlighter / lexer name. This one has to be written in the markdown files next to the opening marker for a code block. Here is an example for html code:

``` html
<html>
  <head>
	<title>
	</title>
  </head>
  <body>
  </body>
</html>
```

The following command line command can be used to output a list of supported lexers:

rougify list