Syntax highlighting code in Eleventy posts

2023-12-16

Background

This site is built using Eleventy, a very nice little static site generator. I've previously written a post about how and why I ended up using it, but that mostly covers how to get up and running with generic content. This is the first post in a little series outlining the different customizations I've made in order for Eleventy to produce just the result I want.

Syntax highlighting

One of the few features outside the basics I was looking for when I compared static site generators was syntax highlighting of code blocks. I often write about programming-related topics here, and having syntax highlighting makes any code snippets included much more pleasant to read. Luckily there's an official Eleventy plugin for that, which is using Prism under the hood. Prism has support for a long long list of languages (although I'm not sure whether all of them are included in the Eleventy plugin), and it seems to be both realizable and really fast as well.

There are three steps involved in setting up syntax highlighting:

Installing the plugin
Adding CSS for the code color scheme
Tagging your code blocks with the language used

Installation

The plugin is installed using npm:

npm install @11ty/eleventy-plugin-syntaxhighlight --save-dev

Once installed it's available in the local Node environment, and can be added to Eleventy with just a couple of lines in .eleventy.js:

const syntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");

module.exports = function (eleventyConfig) {
    eleventyConfig.addPlugin(syntaxHighlight);

    // Further configuration ...

    return eleventyConfig;
};

If you just want to get up and running, that's all there is to the installation step. You can also pass an options object to the addPlugin function to adjust the settings for the plugin as well, but I'm guessing the defaults are fine for most people.

Adding CSS

Now Prism will run, and automatically introduce some additional markup (a lot of <span> tags, to be precise) to the HTML produced from the code blocks, but to actually see any visible syntax highlighting you also need to include a Prism theme in your site. This is a small CSS file dictating the color and style of different elements of the code. There are plenty of themes to choose from, and if none of them suit your needs you can of course modify one, or create your own from scratch. Some of the more popular themes are available from various CDNs, but I decided to include mine as part of the site CSS.

Languages

After adding the CSS you're technically all set, but at this point I still wasn't getting any syntax highlighting. I'm not sure whether this is theme specific, but to finally see the colorized code in all its glory I also had to tag the code blocks with the corresponding programming language:

```html
<h1>Spatula City!</h1>
```

```css
body {
    background: lime;
    color: red;
}
```

```js
console.log("Hello world");
```

Please refer to the list of supported languages to see the what tag to use for different languages. If you're using a template language other than Markdown, please refer to the plugin documentation for how to utilize syntax highlighting.

Conclusion

I really like the syntax-highlighted code blocks and I'm very happy with the way this plugin works. I am however a little bit worried that the highlighting actually makes the code much less user-friendly for readers using text-to-speech devices, screen readers, and similar technologies. I'll have to investigate further to understand if this actually is a problem. Perhaps the fact that Prism only seems to inject <span> tags means it doesn't interfere with assistive technology. If it indeed is a problem I would really like to find an elegant solution to it, so if you happen to know more about this, please let me know.