Tech Notes
Notice: Time waits for no one, and doubly so for technical information. This was posted 4 months ago. Although best efforts are made to keep content current, it’s advised to verify that this is the case here.

Code Highlighting with Prism in Drupal

Posted on 2019-03-31

If you find the need to display code snippets in your content, it's relatively easy in HTML5 to display this content as <code> elements. Beyond basic styling, though, usable code highlighting is often best accomplished with Javascript frameworks rather than CSS alone.

Among the better options is Prism.js, which in addition to being lightweight code-wise, gives a number of options on how you may wish to present code. Furthermore, if you need to remove it from your project at a later time, your underlying content won't be affected.

Installation is fairly straightforward, and once set up requires little markup in order to present compelling and user-friendly technical content.

Installation and Setup

Although there is the Prism module, as well as other paths, this method focuses on loading Prism in Drupal 8 on a per-theme basis. For more details, you may want to check out the Drupal documentation. This also assumes you are using a custom theme in your install. If not, it's advisable to do so in order to avoid overwrites to a core theme when Drupal is updated (and good practice to never modify core).

First, you will want to download Prism. If you’re pretty sure about what code languages you want to display, as well as any themes, you can create a tailored library on the Prism.js site that will exclude any code you won't need, in order to boost performance. In this demonstration, I'm using the Javascript caching and aggregation built into Drupal core (under /admin/config/development/performance) to optimize the code.

Place the Prism folder in: [theme-name]/js. If your theme doesn't have a js folder already, create one (it will make keeping things straight much easier).

In your [theme name]/[theme name]libraries.yml, you'll want to add this:

global_styles:
  version: VERSION
  css:
    theme:
      js/prism/themes/prism.css: {}
  js:
    js/prism/prism.js: {}

Adding this will have the Prism library load on every page of your installation.

 

For performance, you may want to consider loading Prism on a per-page or content type basis. To do that, add this to your [theme name]/[theme name]libraries.yml:

prism:
  version: 1.16.0
  js:
    js/prism/prism.js: {}
  css:
    theme:
      js/prism/themes/prism.css: {}

 

Then, to call it, per specific page, or content type, add this to your [layout template name].html.twig, preferably near the </body> tag:

{{ attach_library('[theme name]/prism') }}

With either approach, once you have cleared your site caches, you should be good to go.

Adding Code Content

With the Prism library now loading, you will want to add this to your body content for a single line of code:

<code class="language-[selected language here]">Code Here</code>

For longer code blocks, add this:

<pre><code class="language-[selected language here]">Use this for large code blocks.
</code></pre>

In both cases, you'll want to add the above code in source code view, first, then switch to standard view to paste in or enter code. If you don’t see it displaying, you may want to check your text format being used—out of box, Drupal's Full HTML format should be able to display this. If not, you may need to check your input filters under /admin/config/content/formats. Often, display issues can come down to settings in the Limit allowed HTML tags and correct faulty HTML and Display any HTML as plain text settings. Generally, both should be either be turned off, or carefully limited.

Since there are potential security issues, it may be worth it to consider which HTML tags are allowed for display.

To set which language to use, change the class to a supported language, such as langauge-css or language-php. This can also be entered shorthand as lang-php. If you want to display HTML, it’s stripped out by default in Prism. To get around this, use language-markup.

Extending Prism

In order to take advantage of additional styles and plugins, you want to add them to your libraries.yml file. As an example, I’ve added the Okaidia theme, as well as the Line Numbers plugin (which is being used to display the code here). When doing so, be sure to add all relevant CSS and/or JS files:

prism:
  version: 1.16.0
  js:
    js/prism/prism.js: {}
    js/prism/plugins/line-numbers/prism-line-numbers.min.js: {}
  css:
    theme:
      js/prism/themes/prism.css: {}
      js/prism/themes/prism-okaidia.css: {}
      js/prism/plugins/line-numbers/prism-line-numbers.css: {}

Hopefully, this will help with your code display needs in Drupal. For more information regarding Prism, check out the documentation.