Syntax highlight with Rouge in Jekyll

Syntax highlight with Rouge in Jekyll

Overview

While using Markdown in Jekyll, it’s easy to insert beautiful code blocks into blog posts.

By default, Jekyll 3 and above comes with Rouge, a pure Ruby syntax highlighter which supports 98 languages. Since Rouge themes are compatible with Pygments’s stylesheets, it’s nice for us to choose the favourable styles.

Install Rouge

Once you have installed Jekyll 3 or above versions, Rouge is already there. If you’re still using Jekyll 2, it’s also quick and painless to install it. Just open your favourite command line tool and enter the following command:

gem install rouge

Then, in your _config.yml, set Rouge as your syntax highligher:

highlighter: rouge

Theme and colour

Rouge will help rendering the code snippets in your Markdown files into HTML pre and code tags. The further step is style it using CSS.

In Jekyll’s official document: stylesheets for syntax highlighting, there is an example stylesheet (syntax.css) that you can use.

Besides, Rouge is 100% compatible with Pygments’s stylesheets, you can choose one and use it on your site.

Here is a code block written in C language, you can preview the Pygments predefined styles at http://pygments.org/demo/6350479/?style=manni.

Once you found your favourite style, view the page source to find the pygments.css. Copy or save it to your site and load this css file in the layout file (e.g. _layouts/default.html):

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

As all of those Pygments stylesheet uses .syntax as the default class, you need to replace the .syntax with .highlight class in the pygments.css file.

Implement

Wrap the code snippets in Markdown posts like this:

{% highlight ruby linenos %}
...
...
{% endhighlight %}

In this way of using Liquid tag highlight, you can add language identifier (here is ruby) or its supported aliases (rb for ruby). Here is the list for supported languages:

  • actionscript: ActionScript [aliases: as,as3]
  • apache: configuration files for Apache web server
  • apiblueprint: Markdown based API description language. [aliases: apiblueprint,apib]
  • applescript: The AppleScript scripting language by Apple Inc. (http://developer.apple.com/applescript/)
  • biml: BIML, Business Intelligence Markup Language
  • c: The C programming language
  • ceylon: Say more, more clearly.
  • cfscript: CFScript, the CFML scripting language [aliases: cfc]
  • clojure: The Clojure programming language (clojure.org) [aliases: clj,cljs]
  • cmake: The cross-platform, open-source build system
  • coffeescript: The Coffeescript programming language (coffeescript.org) [aliases: coffee,coffee-script]
  • common_lisp: The Common Lisp variant of Lisp (common-lisp.net) [aliases: cl,common-lisp,elisp,emacs-lisp]
  • conf: A generic lexer for configuration files [aliases: config,configuration]
  • coq: Coq (coq.inria.fr)
  • cpp: The C++ programming language [aliases: c++]
  • csharp: a multi-paradigm language targeting .NET [aliases: c#,cs]
  • css: Cascading Style Sheets, used to style web pages
  • d: The D programming language(dlang.org) [aliases: dlang]
  • dart: The Dart programming language (dartlang.com)
  • diff: Lexes unified diffs or patches [aliases: patch,udiff]
  • eiffel: Eiffel programming language
  • elixir: Elixir language (elixir-lang.org) [aliases: elixir,exs]
  • erb: Embedded ruby template files [aliases: eruby,rhtml]
  • erlang: The Erlang programming language (erlang.org) [aliases: erl]
  • factor: Factor, the practical stack language (factorcode.org)
  • fortran: Fortran 95 Programming Language
  • gherkin: A business-readable spec DSL ( github.com/cucumber/cucumber/wiki/Gherkin ) [aliases: cucumber,behat]
  • glsl: The GLSL shader language
  • go: The Go programming language (http://golang.org) [aliases: go,golang]
  • gradle: A powerful build system for the JVM
  • groovy: The Groovy programming language (http://www.groovy-lang.org/)
  • haml: The Haml templating system for Ruby (haml.info) [aliases: HAML]
  • handlebars: the Handlebars and Mustache templating languages [aliases: hbs,mustache]
  • haskell: The Haskell programming language (haskell.org) [aliases: hs]
  • html: HTML, the markup language of the web
  • http: http requests and responses
  • ini: the INI configuration format
  • io: The IO programming language (http://iolanguage.com)
  • java: The Java programming language (java.com)
  • javascript: JavaScript, the browser scripting language [aliases: js]
  • jinja: Django/Jinja template engine (jinja.pocoo.org) [aliases: django]
  • json: JavaScript Object Notation (json.org)
  • json-doc: JavaScript Object Notation with extenstions for documentation
  • jsonnet: An elegant, formally-specified config language for JSON
  • julia: The Julia programming language [aliases: jl]
  • kotlin: Kotlin http://kotlinlang.org
  • liquid: Liquid is a templating engine for Ruby (liquidmarkup.org)
  • literate_coffeescript: Literate coffeescript [aliases: litcoffee]
  • literate_haskell: Literate haskell [aliases: lithaskell,lhaskell,lhs]
  • llvm: The LLVM Compiler Infrastructure (http://llvm.org/)
  • lua: Lua (http://www.lua.org)
  • make: Makefile syntax [aliases: makefile,mf,gnumake,bsdmake]
  • markdown: Markdown, a light-weight markup language for authors [aliases: md,mkd]
  • matlab: Matlab [aliases: m]
  • moonscript: Moonscript (http://www.moonscript.org) [aliases: moon]
  • nasm: Netwide Assembler
  • nginx: configuration files for the nginx web server (nginx.org)
  • nim: The Nim programming language (http://nim-lang.org/) [aliases: nimrod]
  • objective_c: an extension of C commonly used to write Apple software [aliases: objc]
  • ocaml: Objective CAML (ocaml.org)
  • pascal: a procedural programming language commonly used as a teaching language.
  • perl: The Perl scripting language (perl.org) [aliases: pl]
  • php: The PHP scripting language (php.net) [aliases: php,php3,php4,php5]
  • plaintext: A boring lexer that doesn’t highlight anything [aliases: text]
  • powershell: powershell [aliases: posh]
  • praat: The Praat scripting language (praat.org)
  • prolog: The Prolog programming language (http://en.wikipedia.org/wiki/Prolog) [aliases: prolog]
  • properties: .properties config files for Java
  • protouf: Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data [aliases: proto]
  • puppet: The Puppet configuration management language (puppetlabs.org) [aliases: pp]
  • python: The Python programming language (python.org) [aliases: py]
  • qml: QML, a UI markup language [aliases: qml]
  • r: The R statistics language (r-project.org) [aliases: r,R,s,S]
  • racket: Racket is a Lisp descended from Scheme (racket-lang.org)
  • ruby: The Ruby programming language (ruby-lang.org) [aliases: rb]
  • rust: The Rust programming language (rust-lang.org) [aliases: rs]
  • sass: The Sass stylesheet language language (sass-lang.com)
  • scala: The Scala programming language (scala-lang.org) [aliases: scala]
  • scheme: The Scheme variant of Lisp
  • scss: SCSS stylesheets (sass-lang.com)
  • sed: sed, the ultimate stream editor
  • shell: Various shell languages, including sh and bash [aliases: bash,zsh,ksh,sh]
  • shell_session: A generic lexer for shell session and command line [aliases: terminal,console]
  • slim: The Slim template language
  • smalltalk: The Smalltalk programming language [aliases: st,squeak]
  • smarty: Smarty Template Engine [aliases: smarty]
  • sml: Standard ML [aliases: ml]
  • sql: Structured Query Language, for relational databases
  • swift: Multi paradigm, compiled programming language developed by Apple for iOS and OS X development.(developer.apple.com/swift)
  • tap: Test Anything Protocol [aliases: tap]
  • tcl: The Tool Command Language (tcl.tk)
  • tex: The TeX typesetting system [aliases: TeX,LaTeX,latex]
  • toml: the TOML configuration format (https://github.com/mojombo/toml)
  • tulip: The tulip programming language http://github.com/jneen/tulip [aliases: tlp]
  • twig: Twig template engine (twig.sensiolabs.org)
  • typescript: TypeScript, a superset of JavaScript [aliases: ts]
  • vb: Visual Basic [aliases: visualbasic]
  • verilog: The System Verilog hardware description language
  • viml: VimL, the scripting language for the Vim editor (vim.org) [aliases: vim,vimscript,ex]
  • xml: XML
  • yaml: Yaml Ain’t Markup Language (yaml.org) [aliases: yml]

If you don’t need the line numbers, you can use fenced_code_blocks in Jekyll just with triple backticks like this:

```rb
your code here
```

Example

For example, this snippet of Ruby code:

def show
  puts "Outputting a very lo-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-ong lo-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-ong line"
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end

Just using the following markups in the Markdown file:

```rb
def show
  puts "Outputting a very lo-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-ong lo-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-ong line"
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end
```

The “fenced_code_blocks” is the most simple and recommended way for code highlights, hope you enjoy coding.

avatar

Frank Lin

Code learning...

Say something Login