Highlight JS Syntax Highlighter

By: Chris Dunn

When you're writing a technical blog, you need a good syntax highlighter.  I didn't want to point to external files or even GitHub Gists for every sample or partial piece of code.  While there are probably hundreds of tools for the job, I ended up choosing Highlight JS, and couldn't be happier.  Here's how I went about setting it up including a minor customization I added for the display.  

Highlight JS

Highlight JS is a bare bones syntax highlighter with formatting for many different languages. It even allows you to customize styles for your own implementation. In fact, it is the highlighter used on Microsoft's own .net documentation site. Hopefully that alone will keep it alive for years to come.

Basic Setup

As with all components and libraries, you will need to include a script reference to the script files.  I've included the link to a hosted version of the library.  I like to use the publicly hosted version of files when I can, for many reasons.  But even when I do, I like to grab a version and put somewhere as a fallback if something goes wrong with the hosted version.  It can and does happen.

<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js" type="text/javascript"></script>
	

The core of the Syntax Highlighters script, is wrapping keywords in elements and assigning styles to those elements.  The language you target determines which keywords get wrapped, but the color and display of those styles is determined by the theme.  There are a lot of existing themes available, and as I said, you can also create your own.  If you're going to do that I suggest you simply modify and existing theme and save yourself a few headaches.  Here is the one I am using, a styling similar to GitHub Gist display.

/*

github.com style (c) Vasily Polovnyov <vast@whiteants.net>

*/

/**
 * GitHub Gist Theme
 * Author : Louis Barranqueiro - https://github.com/LouisBarranqueiro
 */

.hljs {
  display: block;
  background: hsla(0, 0%, 98%, 1);
  padding: 0.5em;
  color: #333333;
  overflow-x: auto;
border:solid 1px hsl(0, 0%, 93%);
}

.hljs-comment,
.hljs-meta {
  color: #969896;
}

.hljs-string,
.hljs-variable,
.hljs-template-variable,
.hljs-strong,
.hljs-emphasis,
.hljs-quote {
  color: #df5000;
}

.hljs-keyword,
.hljs-selector-tag,
.hljs-type {
  color: #a71d5d;
}

.hljs-literal,
.hljs-symbol,
.hljs-bullet,
.hljs-attribute {
  color: #0086b3;
}

.hljs-section,
.hljs-name {
  color: #63a35c;
}

.hljs-tag {
  color: #333333;
}

.hljs-title,
.hljs-attr,
.hljs-selector-id,
.hljs-selector-class,
.hljs-selector-attr,
.hljs-selector-pseudo {
  color: #795da3;
}

.hljs-addition {
  color: #55a532;
  background-color: #eaffea;
}

.hljs-deletion {
  color: #bd2c00;
  background-color: #ffecec;
}

.hljs-link {
  text-decoration: underline;
}

Usage

Implementing the Highlighter to your markup doesn't require too much overhead or extra html.  All you need to do is wrap your code blocks in a pre tag.  You may have to play with the indentation of the internal content if you are copying directly from an IDE.  Each language has an associated class that you use for the pre tag.  C# = cs, CSS=css, Javascript = javascript .  Full list of languages can be found here. It does have the feature of auto-detecting the language, which I didn't want to rely on. 

<pre class="cs">
void main()
{
	Console.WriteLine("Hello World.");
}
</pre>

Header Customization

I like that HighlightJS doesn't have a lot of extras, which keep it simple and small.  I did however want one option that wasn't available. I wanted a common way to display a descriptive title on the block of code (name of language). So, I added an additional element styled with the class .code-header.  Rather than manually add the additional markup for each code block, I created a script to add the styled div tag before the pre tag with the code.  By setting the data-lang data attribute on the pre tag, you can specify the display text.  

.code-header{color: hsl(0, 0%, 60%); padding:5px;border:solid 1px hsl(0, 0%, 93%); border-bottom:solid 1px hsl(0, 0%, 98%); background-color:hsla(0, 0%, 98%, 1);font-weight:normal;}
 

$(document).ready(function() {
	  $('pre').each(function(i, block) {
		var lang = $(block).attr('data-lang');  
		if (lang === undefined) lang = 'Code';
		$('<div class='code-header'>' + lang + '</div>' ).insertBefore(block);
	  	hljs.highlightBlock(block);  
  });

<pre class="cs" data-lang="C#">
void main()
{
	Console.WriteLine("Hello World.");
}
</pre>

I looked at a number of options for displaying code, and this one worked best for me. It doesn't have a lot of options like some others do, like line numbers, but that wasn't something important to me at this point. I also found the minor customization I needed, was easy enough to implement on my own, rather than include the kitchen sink from the start.