Intro to Rouge

Rouge is a syntax highlighter written in Ruby to provide syntax highlighting for code written on HTML pages. According to Github Docs,

By default, code blocks on your site will be highlighted by Jekyll. Jekyll uses the Rouge highlighter, which is compatible with Pygments. Pygments has been deprecated and not supported in Jekyll 4. If you specify Pygments in your _config.yml file, Rouge will be used as the fallback instead. Jekyll cannot use any other syntax highlighter, and you’ll get a page build warning if you specify another syntax highlighter in your _config.yml file.

In this article, we will use Rouge (syntax highlighter), Kramdown (Markdown parser) and Jekyll to build our blog. Since Rouge and Kramdown are now default setting, you don’t need to specify them in your _config.yml, but if you want to, add following code into it.

markdown: kramdown
kramdown:
  syntax_highlighter: rouge

Syntax Highlighting

Pick a Theme

First, add a syntax highlighting CSS into your project. Here I pick github style.

$ rougify style github > css/github-style.css

Include the CSS file in your head.html.

<link href="/css/github-style.css" rel="stylesheet" >

You can find your favorite theme in this page.

Write Your Code Block

We write posts in markdown files, and Jekyll will generate HTML for us. In your markdown file, add following javascript code block:

{% highlight javascript %}
document.write("JavaScript is a simple language for javatpoint learners");
alert("This is a test");
{% endhighlight %}

The resulted post would show javascript syntax highlighting.

document.write("JavaScript is a simple language for javatpoint learners");
alert("This is a test");

Instead of liguid tags, we can also use markdown sytax. In your markdown file, add following javascript code block:

```javascript
document.write("JavaScript is a simple language for javatpoint learners");
alert("This is a test");
```

The resulted post would be the same

document.write("JavaScript is a simple language for javatpoint learners");
alert("This is a test");

Of course, you can modify javascript to be other languages.

Enable Line Number

You can add line number to your code block by specifying the linenos option. In your markdown file, add following javascript code block:

{% highlight javascript linenos%}
document.write("JavaScript is a simple language for javatpoint learners");
alert("This is a test");
{% endhighlight %}

The resulted code block would show line numbers.

1
2
document.write("JavaScript is a simple language for javatpoint learners");
alert("This is a test");

You can set showing line numbers to be default setting in your _config.yml. Add following code into it.

markdown: kramdown
kramdown:
  syntax_highlighter: rouge
  syntax_highlighter_opts:
    block:
      line_numbers: true

Escape Liquid Tags

If you have liquid tags in your code block, the resulting html may look weird. We need to escape liquid tags by using raw tag. See this stackoverflow post.

Rounded Corners, Padding and Horizontal Scrollbar

You may notice that (1) the corners of the code block are right angles; (2) the padding is too small; (3) if the line is too long, the code can run out of block. I wrote some simple CSS codes to address these issues. Add following code into thankful-style.css.

/* 
    add rounded corners, padding syntax and horizontal scroll bar to the code block
    author: epigone707
*/
pre.highlight {
  padding: 7px;
  /* cause a scrolling mechanism to be provided for overflowing boxes */
  overflow-x: auto; 
}

figure.highlight>pre {
  padding: 7px;
  overflow-x: auto;
}

.highlight {
  border-radius: 5px;
}

Now the code block is nice and neat.

def foo(name):
  print("this is really long long long long long long long long long long long long long long long long long sentence.")
  return