One of the challenges I faced when getting my new blog theme up and running was getting highlight.js working as I wanted it to. The library has support for a riduculous number of languages, and provides theming capabilities, so it was the clear choice when it came to syntax highlighting for the web. The challenge is that tt's not just adding simple script tag and you're done with it. They seem to expect you to know what you're doing when consuming the library.
Remember: this is a good thing.
Lucky for us, the folks in charge of highlight.js have given us all the tools we need to make using the library in our application nice and performant. In my case, I use Bower as my package manager and Gulp as my build system, which worked well once I figured out what I was doing. Let me walk you though it.
Installing Highlight.js with Bower
To start, you'll need to add highlight.js to your project using Bower.
Building Highlight.js with Gulp
The hard work has already been done by the highlight.js team, as they have already included a lovely build tool for us to use. You can read about the details here in the building and testing documentation.
If you read the docs earlier, you know that there is a NodeJS script in the
tools directory that will do all the heavy lifting. All we need to do in our Gulp task is use that script.
Here's my Gulp task:
It looks a little strange for a gulp task, but all I'm doing is executing a shell command using the
exec in NodeJS to spawn a child process. The important part is in the
command variable. Let's walk through it.
First, I'm moving into the root directory of the highligh.js.origin package we previously installed using Bower.
Then, I'm installing the dependencies that are needed by the provided build tool.
Finally, I'm running the build command as specified in the documentation. This part should be changed to make sure it includes the languages you want to display in your application. Details are in their documentation.
The rest is just outputting the standard out and standard error streams to the console, and calling the Gulp callback to make sure we come back to our original process, as per the Gulp documentation.
If everything is done correctly, you should have a new
build folder in the
highlight.js.origin folder that contains your newly build library.
Building Highlight.js Themes for SASS
I suppose this part is optional, but it shouldn't be.
To make optimize your site, you should be minimizing the number of requests that the client browser needs to make to get all the required resources for your application. For styling, that involves concatenanting all of your styles and style libraries into a single file.
To do this, I use SASS or, more specifically, gulp-sass to build all of my stylesheets and combine them into a single CSS file as described by the SASS documentation. I'm going to assume that you're doing the same, or at least something similar in your application that will be using highlight.js.
Because SASS only handles combining other
scss files, I copy the theme stylesheet into a newly named
scss file. Here's my gulp task for that:
Then in my main stylesheet, I include:
This will bring in the
highlight.js.scss file when I build my styles using
gulp-sass in my application stylesheet build task.
And now highlight.js ready to Use in our application.
Caveat About Using Highlight.js with Markdown
My post assumes that for any blocks of text where you want syntax highlighting you're comfortable using the default highlight.js usage behaviour of wrapping the code with
Although I blog using Markdown, at the time of this writing I still wrap my text with these elements, unlike GitHub flavoured markdown that lets define the language using regular Markdown syntax.
The reason for this, is that my blog engine renders the Markdown syntax with a bunch of extra HTML woven throughout the code to display it without the need for a library like highlight.js.
It might not be a big deal for you or your project, but I thought it was something you should be aware of when if you're planning on using highlight.js in your application.