Thanks to a quite overdue update of Hugo on our build system¹, our website can now harness the full power of Hugo code highlighting for Markdown-based content. What’s code highlighting apart from the reason behind a tongue-twister in this post title? In this post we shall explain how Hugo’s code highlighter, Chroma, helps you prettify your code (i.e. syntax highlighting), and accentuate parts of your code (i.e. line highlighting).

Make your code look pretty

If you notice and appreciate the difference between

a <- c(1:7, NA)
mean(a, na.rm = TRUE)

and

a <- c(1:7, NA)
mean(a, na.rm = TRUE)

you might agree with Mara Averick’s opinion,

Syntax highlighting! ????️ Just do it. Life is better when things are colourful.

Syntax highlighting means some elements of code blocks, like functions, operators, comments, etc. get styled differently: they could be colored or in italic.

Now, how do the colors of the second block appear?

First of all, it’s a code block with language information, in this case R (note the r after the backticks),

```r
a <- c(1:7, NA)
mean(a, na.rm = TRUE)
```

as opposed to

```
a <- c(1:7, NA)
mean(a, na.rm = TRUE)
```

without language information, that won’t get highlighted – although some syntax highlighting tools, not Hugo Chroma, do some guessing.

There are in general two ways in which colors are added to code blocks, client-side syntax highlighting and server-side syntax highlighting. The latter is what Hugo supports nowadays but let’s dive into both for the sake of completeness (or because I’m proud I now get it²).

Client-side syntax highlighting

In this sub-section I’ll mostly refer to highlight.js but principles probably apply to other client-side syntax highlighting tools. The “client-side” part of this phrase is that the html that is served by your website host does not have styling for the code. In highlight.js case, styling appears after a JS script is loaded and applied.

If we look at a post of Mara Averick’s at the time of writing, the html of a block is just

<pre class="r"><code>pal_a <- extract_colours("https://i.imgur.com/FyEALqr.jpg", num_col = 8)
par(mfrow = c(1,2))
pie(rep(1, 8), col = pal_a, main = "Palette based on Archer Poster")
hist(Nile, breaks = 8, col = pal_a, main = "Palette based on Archer Poster")</code>

Now, using Firefox Developer Console,

we see colors come from CSS classes starting with “hljs”.

And in the head of that page (examined via “View source”), there’s

<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

which is the part loading and applying highlight.js to the page. Now, how does it know what’s for instance a string in R? If we look at highlight.js highlighter for the R language, authored by Joe Cheng in 2012, it’s a bunch of regular expressions, see for instance the definition of a string.

        className: 'string',
        contains: [hljs.BACKSLASH_ESCAPE],
        variants: [
          {begin: '"', end: '"'},
          {begin: "'", end: "'"}
        ]

When using highlight.js on your website, you might need to specify R as a supplementary language in your config, since some languages are bundled by default whilst others are not. You could also whip up some code to conditionally load supplementary highlight.js languages.

A big downside of client-side syntax highlighting is loading time: it appears quite fast if your internet connection isn’t poor, but you might have noticed code blocks changing aspect when loading a web page (first not styled, then styled). Moreover, Hugo now supports, and uses by default, an alternative that we’ll describe in the following subsection and take advantage of in this post’s second section.

Server-side syntax highlighting

In server-side syntax highlighting, with say Pygments or Chroma (Hugo default), your website html as served already has styling information.

With Chroma, that styling information is either:

• hard-coded in html³, as is since recently the case of tidyverse.org and blog.r-hub.io;

The html source for one of the blocks of the page screenshot above is

div class="highlight"><pre style=";-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-r" data-lang="r">df <span style="color:#666">%>%</span> 
  <span style="color:#00f">group_by</span>(g1, g2) <span style="color:#666">%>%</span> 
  <span style="color:#00f">summarise</span>(a <span style="color:#666">=</span> <span style="color:#00f">mean</span>(a), b <span style="color:#666">=</span> <span style="color:#00f">mean</span>(b), c <span style="color:#666">=</span> <span style="color:#00f">mean</span>(c), d <span style="color:#666">=</span> <span style="color:#00f">mean</span>(c))
</code>