How to show code in a page; Prism code highlighter

I recently had to create some documentation at work and needed to highlight several pieces of code for each component. I took it for granted since it's built in in most mature platform such as Github or Dev.to. What a mistake.

I needed to find a solution that would show my code extract in a clear and neat way alongside my text. That's how I came across Prism. And today we will see how to manage such an integration and how to cope with the few difficulties here and there.

Integrate Prism

Prism.js' highlighter is very lightweight and relies on both a CSS and a JS file. We have three integration options: Copy-pasting, downloading or using a CDN.

The first two options start from the Prism.js' download page. We can see default options are selected but we can change it to fit our needs. Indeed we can opt for our preferred theme, languages and plugins.

Once we are satisfied with our settings, we can directly copy the codes from the page or download the files.

The third option expects a CDN provider, let it be cdnjs or jsDelivr where we select the right link to match our desired settings.

Work with Prism

As an example I will use the default settings and use a CDN. That means that what we need to do is to integrate those CDN links in the HTML code.

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/themes/prism.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.20.0/prism.min.js"></script>

Now let's see how we can write the elements to be highlighted by Prism.
First we use a pre element with a nested code element. This code element will define the language in its class (ie: language-css). And finally inside of it, we will write our code to be highlighted.

<pre>
  <code class="language-css">
    img {
      display: block;
      width: 100%;
      height: auto;
    }
  </code>
</pre>

And this is how Prism would render it.

Fix unexpected spaces

The highlighted version of our CSS above faces one problem. Because of how pre elements work, Prism takes unexpected line breaks and extra spaces (used for better code clarity) into account. Let's fix this with an old trick of commenting out.

<pre>
  <code class="language-css"><!--
  -->img {
    display: block;
    width: 100%;
    height: auto;
  }<!--
  --></code>
</pre>

See the difference below.

Work with HTML

We saw that CSS is easy, and it goes the same way with JS. However, HTML is more complicated, because Prism doesn't know where to start highlighting. The way to work with HTML is to replace all the < with <. We can also replace all the > with >. While the second step isn't mandatory I still do it because it feels safer.

<pre>
  <code class="language-markup"><!--
  -->&lt;div&gt;
    &lt;img src="example.png"&gt;
  &lt;/div&gt;<!--
  --></code>
</pre>

Giving this result.

I recommend the plugin Unescaped markdwon if you work heavily with HTML code to highlight. The plugin will handle the replacements.

Live example on Codepen

Isn't an example worth a million words? 😄

Prism has tons of settings. Take your time to explore and find the ones fitting your needs.

Keep playing to learn! 🔥

If you find value in what I offer don't hesitate and buy me a coffee 😇

Note: As stated in my introduction, of course we can use Markdown as it is in Dev.to or Github; We could also use Codepen or JsFiddle. Sometimes we just don't benefit from these tools and that's where Prism is so handful.