Version 0.3.0 Released

I recently received a question about how to get source code to render correctly on a blog post. After doing some research, I found the available code rendering less than desirable with the current version of gh-pages-blog, mainly because syntax highlighting wasn’t available. So I added some features to better support source code rendering and syntax highlighting.

The first thing you’ll notice is the inclusion of a syntax.css file now. Thanks to Tom Preston-Werner for making this file available under the MIT License.

If you don’t like how the syntax highlight works, you can either edit the syntax.css or you can create a new file. If you create a new file, you’ll want to update the syntax-highlighting settings in the _config.yml file to reference the new file. If you don’t want to use syntax highlighting at all, you can also disable the loading of the css via the _config.yml.

In order to get the source code to render correctly on your blog post and pages, you’ll need to wrap the code in the highlight tags supported by Jekyll.

{% highlight text %}
code goes here
{% endhighlight %}

It’s very important to include text in the tag, otherwise the GitHub page won’t build. Jekyll will render the line breaks and spacing correctly between the highlight tags, so it shouldn’t be necessary to do any other formatting. It’s not necessary to wrap your code in <pre><code></code></pre> when using the highlight tag.

Adding the highlight tags around some sample code would result in the following output:

function code_example() {
  console.log("Showing the plain text rendering of code using gh-pages-blog.");
}

In order to turn on syntax highlighting for a particular language, you’ll also need to include the language in the highlight markup tag by replacing the word text with the proper language (for javascript, {% highlight javascript %}).

function code_example_with_javascript_syntax_highlights() {
  console.log("Showing the syntax highlighting rendering of code using gh-pages-blog.");
}

For a complete list of languages with syntax highlight, please see the lexers documentation of the Pygments project. Pygments is used by Jekyll, and Jekyll is used by the GitHub:Pages. The rabbit hole can go deeper, but I don’t think it’s necessary to go there at this time.

If you want to include line numbers in your source code listings, you just need to add linenos=table to the {% highlight javascript linenos=table %} tag.

1
2
3

function code_example_with_line_numbers() {
  console.log("Showing the line number rendering of code using gh-pages-blog.");
}

You can use linenos without the =table, but the code output puts the line numbers inline with the text, making it very difficult to copy and share.

Happy Blogging!

Dereck