How to Install Prism.js in Grav CMS

prism-js

If you are running a website with Grav and want to add syntax highlighting to your posts, one if the easiest ways to do it is with Prism.js. It will take your plain old code blocks and turn them from this:

 <!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>

</body>
</html> 

to this:

 <!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>

</body>
</html> 

If this is what you are looking for, follow the directions below.

Download Prism.js Files

Head over to Prism.js and choose the theme you want to use. This will dictate the base background color and syntax highlighting scheme. At the time of this writing, the selection options are on the right side, and the example shows below.

prism-js-theme

After selecting a theme, hit the Download button.

Make sure the Minified Version is selected, then go through the list of languages and select any that you want to use. The more languages you add, the larger the .css and .js files will be. So only choose ones you will be using.

There are additional plugins you can add to your install, but those are beyond the scope of this post.

Once you have selected all the languages you want to use, download the css and js files at the bottom.

prism-js-download

Add Files to Grav

With the prism.css and prism.js files in hand, head over to your Grav root directory. The next step is adding these two files to the appropriate folders within your child theme.

Move prism.css to /user/themes/YOUR-CHILD-THEME/css/.

Move prism.js to /user/themes/YOUR-CHILD-THEME/js.

Edit Theme

With the files in place, the last thing to do is tell Grav to use them.

Add CSS

Open your child theme's base.html.twig file, which should be located in /user/themes/YOUR-CHILD-THEME/templates/partials/. Within the <head> tag, look for something that looks like this:

{% block stylesheets %}
    {% do assets.addCss('theme://css/widget.css') %}
    {% do assets.addCss('theme://css/style.css') %}
    {% do assets.addCss('theme://css/content.css', 101) %}
    {% do assets.addCss('theme://css/sidebar.css', 100) %}
    {% do assets.addCss('theme://css/lightbox.css') %}
    {% do assets.addCss('theme://css/custom.css') %}

Copy the custom.css line and paste it at the bottom. Then change one of them to prism.css. Its recommended to keep custom.css as the bottom, so any changes you make there will be the final override (being cascading style sheets, and all.)

The final result should look something like this:

{% block stylesheets %}
    {% do assets.addCss('theme://css/widget.css') %}
    {% do assets.addCss('theme://css/style.css') %}
    {% do assets.addCss('theme://css/content.css', 101) %}
    {% do assets.addCss('theme://css/sidebar.css', 100) %}
    {% do assets.addCss('theme://css/lightbox.css') %}
    {% do assets.addCss('theme://css/prism.css') %}
    {% do assets.addCss('theme://css/custom.css') %}

Add JavaScript

Now do the same thing for the prism.js file. It should be in the same <head> tag, and the final result should look something like this:

{% block javascripts %}
    {% do assets.add('jquery',101) %}
    {% do assets.add('theme://js/scripts.js') %}
    {% do assets.add('theme://js/video.js') %}
    {% do assets.add('theme://js/prism.js') %}

Adding the Language Class in Markdown

When writing your content, its very easy to add the appropriate language class by adding the name of the language immediately after the first three ticks that open the code block.

You can find the appropriate name to use on Prism's website here.

Example with html:

```html
 <!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>

</body>
</html> 

Turns into this:

 <!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>

</body>
</html> 

That's it! Now you can add custom syntax highlighting to any content on your Grav website.

Clear Your Cache

As always, remember to clear your site cache. Grav is pretty aggressive on the caching, so if you are not seeing the changes you expect, clear the site cache and your browser cache.

Good luck!

Gravatar

Don't take my word for it. I'm just a random guy on the internet.