Syntax highlighting with Prism.js in Open edX

Important note: Syntax highlighting in your course content is now possible using the Syntax Highlighter XBlock, developed using Prism.js. This method is a more complex way to give you more control over your code samples, but we recommend trying the XBlock first. This method may require you to make some modifications to your Prism CSS to avoid conflicts with the base platform's theme. Use this method at your own risk, as we will be unable to support you in making changes to this third-party package.

Prism.js is a lightweight, open source library that employs a variety of language-specific syntax highlighting styles to make code blocks look beautiful in Open edX. You can try it for yourself over on their website, but here's a picture of some code using our favorite theme, Okaida. (The examples throughout this article will be in the Okaida theme.)

If you need syntax highlighting, chances are you're several steps ahead already, and that's fine. But in this article you'll learn step-by-step how to download the files necessary to use Prism.js, upload them to your course, and use them in your course content. If you'd like, you can also use a CDN for this - but we're going to stick with the old-fashioned method.

Download your files

The first step is actually getting the .js and .css files necessary to bring these styles into your pages. To do that, head over to the download page and select the options you need. We recommend only grabbing the languages you're going to use, as it makes the file lighter and your pages load faster. For similar reasons, make sure you take the minified version, unless you have a specific reason not to. There's a variety of plugins available that can be included in your download, and we definitely recommend checking them out to see if you need any of them for your purposes.

Down at the bottom of the page, you can preview your theme and download the two files you need. Once you have both files, you're done with the Prism.js website, unless you want to look at their tips and tricks.

Add the Prism files to Studio

Inside your course, head over to Files & Uploads, and upload both of your new files to your course.

Once these files are uploaded, we can use them in our course. On the page with your code, you'll insert an HTML component, and include the file info inside that component. Our recommendation is to do this via a common template component that you can easily copy to other pages, such as a footer. It really doesn't matter where on the page it ends up, so long as it's present. You don't need to do this more than once on a single page, but it does have to appear somewhere on every page that you need the syntax highlighting.

In order to use this the most effectively, you may wish to switch out of the Visual Editor to avoid conflicts with your code. To do this either insert your HTML component by using the Raw HTML option...

Or switch your existing HTML component's to open in the Raw editor in the Settings tab of the editor (you'll need to Save and re-open the edit window to switch default editors).

To include our files on our page we first insert the following HTML wherever we want to stash it so that our files are included when the page loads: 

<script src="/static/prism.js"></script>
<link rel="stylesheet" type="text/css" href="/static/prism.css">

Then, where our code blocks appear, we need to add some markup surrounding it to let it know it's a code block, as well as a class telling it to use our specified language:

<pre><code class="language-python">
Your code goes here.
</code></pre>

And that's it! You're done! Note that at first it may not look right. If this happens, simply perform a hard refresh (CTRL+Shift+R or the equivalent for your OS). There's some core platform styling that doesn't always go away the first time you load your code. Once you've got it all set up, you should end up with something that looks a little like this.

Happy coding!