I recently decided that the default syntax highlighting with Jekyll was a bit plain, and wanted to look into customizing it for this wesite but struggled find all of the necessary information in one place. As a reasult I thought it would be a good idea to write this guide.

note: Pygments is currently not supported by Github Pages and it will default to rogue highlighter. However the styles used in this guide will still work for rogue too, and hopefully Pygments support will come soon.

 

What is Pygments?

#some sample ruby code using pygments and a custom style
class HelloWorld
   def initialize(name)
      @name = name.capitalize
   end
   def sayHi
      puts "Hello #{@name}!"
   end
end

hello = HelloWorld.new("World")
hello.sayHi

Pygments is a generic syntax highlighter written in python, which can be used in combination with markdown to provide great looking syntax highlighting in code blocks as seen above. The highlighting for this is fully customizable via css, and there are loads of great presets that can be found around the place (which we will take advantage of in the guide).

Thankfully Pygments has been ported to ruby and as a result can be easily used on websites generated by Jekyll, however for people with limited experience with Jekyll and css (like me) getting this set up can be a bit confusing with the resources available online.

This article will go through a full step by step guide to get Pygments working on your Jekyll website but will assume that you already have a basic website set up with Jekyll before starting. If you don’t, then the Jekyll quickstart guide will get you sorted with that.

 

Step 1: Getting the Right Gems

  • open your Gemfile and add these two gems:
gem 'redcarpet'
gem 'pygments.rb'
  • Then navigate to the root directory of your site in the terminal and type bundle install . You should see an output at the end that looks like this:
Bundle complete! 6 Gemfile dependencies, 32 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

If so then this step is done.

 

Step 2: Installing Pygments

Unfortunately the pygments.rb gem only interprets Pygments into ruby, it still needs the Pygments python library to run.

  • First quickly check to see if you have Python and Pip installed, and which version, by typing Python into the terminal, if it opens up a Python console then read the version and type quit(). Pygments requires version 2.6 or higher or 3.3 or higher for Python3 if your is below that, update Python.

  • Next type pip in terminal. If the pip help options come up continue, if not download pip and continue.

  • Finally in the terminal enter:

pip install Pygments

As long as this completes without errors you’re all good to go to the next step.

 

Step 3: Editing _config.yml

  • Open your _config.yml and remove the line that says:
markdown: kramdown
  • and replace it with:
markdown: redcarpet 
highlighter: pygments

With that done we are ready for the step.

 

Step 4: Setting Up the Syntax Style

Now we need to set up the stylesheet that Pygments will use to format your highlighting. While it is possible to write one yourself from scatch there are loads of different stylesheets available online. My favorite source for them is jwarby’s github page. It allows you to preview the styles before making your decision, and has a great selection.

  • Once you have grabbed the css code for your style of choice create a folder called {sites_root_folder}/assets/css/pygments and then create a new file within that folder. Paste the style code you grabbed earlier and save it as a .css.

  • Finally create a file called main.css (unless you already have one) in {sites_root_folder}/assets/css and in it write:

@import url(pygments/{your_stylesheet_name}.css);

 

If you are already using a theme that had a main.css then you can probably skip this step. This is mainly for people building a theme from scratch, or just sticking to the default Jekyll skin.

Now we have the Pygments stylesheet referenced in our main.css file, but that css file isnt referenced in the html of the posts page. As a result of this if you try to run jekyll serve now you will see that the default highlighting is still in place in your markdown code blocks.

  • Firstly we need to create a folder called _layouts in the root directory if it does not already exist.

  • Next within this folder create a file called post.html , again, so long as it doesn’t already exist.

  • If you are starting from a new jekyll site you will need to fill this file with a basic layout template. head to Jekylls Minima theme Github and copy paste this code into your post.html file

  • Finally add the following code to the top of the html portion of the file:

<head>
<link href="/assets/css/main.css" rel="stylesheet" type="text/css">
</head>

code highlighting on default jekyll post here is the default welcome post with a shiny new Pygment code box

And with that you should have easy to edit syntax highlighting for your code blocks! These make all the difference in making the site look that bit nicer, and adding a bit of color to an otherwise somewhat plain markdown code blocks.