Jekyll, GFM and Syntax Highlighting

GitHub Pages and GitHub Flavoured Markdown

Originally I thought that Jekyll use to host GitHub pages would use GitHub Flavoured Markdown (GFM) as standard and would require no setup, particularly for syntax highlighting. This is not the case and generally for the better.

Setting Jekyll to use GitHub Flavoured Markdown is very easy, it also has advantages for sites that quote code by adding features such as fenced code blocks and changing the way Markdown handles underscores, to name a few.

This post will detail how simple it is to enable GFM and setup Syntax highlighting.

First we change the default Jekyll Markdown parser from Maruku (current default about to be replaced with Kramdown) to redcarpet by updating the Jekyll _config.yml.

markdown: redcarpet

Syntax Highlighting

Now we can use GFM to write our Markdown we need to format the Syntax with in the fenced code blocks. To do this we simply need to add CSS to format the content within the HTML of the fenced code blocks that the redcarpet Markdown parser creates. There are some rather good resources that provide the CSS files for various code palettes and my personal choice (the one used here) is Monokai.

One such resource is pygments-css maintained by Richard Leland which I will highlight in particular due to the GitHub Page hosted repo site that demonstrates the differing palettes in action.

Personally I created my CSS from a Gist and a repo. The Gist by assaki taking the bulk of the highlight CSS and added the first line form this repo file by aahan, adapting the back ground colour and text colour to match with Monokai. By adapting this first line, you get a nice GitHub style border to the Syntax frame, allowing it to sit nicely with in the page.

IT can be found in the linked Gist, but is detailed in code below. All that remained was to link the CSS file in my header _include.

/* Adjusted to give override background and text colour */
.highlight pre, pre, .highlight .hll {
    background-color: #49483E;
    border: 1px solid #ccc;
    padding: 6px 10px;
    border-radius: 3px;
    color: #FFFFFF;
}
/* Highlights taken from https://gist.github.com/asaaki/1007420  for Monokai theme */
.c                 { color: #75715e }               /* Comment                     */
.err               { color: #960050;
                     background-color: #1e0010 }    /* Error                       */
.k                 { color: #66d9ef }               /* Keyword                     */
.l                 { color: #ae81ff }               /* Literal                     */
.n                 { color: #f8f8f2 }               /* Name                        */
.o                 { color: #f92672 }               /* Operator                    */
.p                 { color: #f8f8f2 }               /* Punctuation                 */
.cm                { color: #75715e }               /* Comment.Multiline           */
.cp                { color: #75715e }               /* Comment.Preproc             */
.c1                { color: #75715e }               /* Comment.Single              */
.cs                { color: #75715e }               /* Comment.Special             */
.ge                { font-style: italic }           /* Generic.Emph                */
.gs                { font-weight: bold }            /* Generic.Strong              */
.kc                { color: #66d9ef }               /* Keyword.Constant            */
.kd                { color: #66d9ef }               /* Keyword.Declaration         */
.kn                { color: #f92672 }               /* Keyword.Namespace           */
.kp                { color: #66d9ef }               /* Keyword.Pseudo              */
.kr                { color: #66d9ef }               /* Keyword.Reserved            */
.kt                { color: #66d9ef }               /* Keyword.Type                */
.ld                { color: #e6db74 }               /* Literal.Date                */
.m                 { color: #ae81ff }               /* Literal.Number              */
.s                 { color: #e6db74 }               /* Literal.String              */
.na                { color: #a6e22e }               /* Name.Attribute              */
.nb                { color: #f8f8f2 }               /* Name.Builtin                */
.nc                { color: #a6e22e }               /* Name.Class                  */
.no                { color: #66d9ef }               /* Name.Constant               */
.nd                { color: #a6e22e }               /* Name.Decorator              */
.ni                { color: #f8f8f2 }               /* Name.Entity                 */
.ne                { color: #a6e22e }               /* Name.Exception              */
.nf                { color: #a6e22e }               /* Name.Function               */
.nl                { color: #f8f8f2 }               /* Name.Label                  */
.nn                { color: #f8f8f2 }               /* Name.Namespace              */
.nx                { color: #a6e22e }               /* Name.Other                  */
.py                { color: #f8f8f2 }               /* Name.Property               */
.nt                { color: #f92672 }               /* Name.Tag                    */
.nv                { color: #f8f8f2 }               /* Name.Variable               */
.ow                { color: #f92672 }               /* Operator.Word               */
.w                 { color: #f8f8f2 }               /* Text.Whitespace             */
.mf                { color: #ae81ff }               /* Literal.Number.Float        */
.mh                { color: #ae81ff }               /* Literal.Number.Hex          */
.mi                { color: #ae81ff }               /* Literal.Number.Integer      */
.mo                { color: #ae81ff }               /* Literal.Number.Oct          */
.sb                { color: #e6db74 }               /* Literal.String.Backtick     */
.sc                { color: #e6db74 }               /* Literal.String.Char         */
.sd                { color: #e6db74 }               /* Literal.String.Doc          */
.s2                { color: #e6db74 }               /* Literal.String.Double       */
.se                { color: #ae81ff }               /* Literal.String.Escape       */
.sh                { color: #e6db74 }               /* Literal.String.Heredoc      */
.si                { color: #e6db74 }               /* Literal.String.Interpol     */
.sx                { color: #e6db74 }               /* Literal.String.Other        */
.sr                { color: #e6db74 }               /* Literal.String.Regex        */
.s1                { color: #e6db74 }               /* Literal.String.Single       */
.ss                { color: #e6db74 }               /* Literal.String.Symbol       */
.bp                { color: #f8f8f2 }               /* Name.Builtin.Pseudo         */
.vc                { color: #f8f8f2 }               /* Name.Variable.Class         */
.vg                { color: #f8f8f2 }               /* Name.Variable.Global        */
.vi                { color: #f8f8f2 }               /* Name.Variable.Instance      */
.il                { color: #ae81ff }               /* Literal.Number.Integer.Long */