Adding Syntax Highlight

R

Syntax highlighting

Previously, I posted entries without any syntax highlighting as I was satisfied using basic blogdown and Hugo functions until a Disqus member commented in the previous post to use syntax highlighting. Thus, I tasked myself to learn more about syntax highlighting and to implement them in future posts. Now I’d like to share what I’ve learned.

There are various ways to highlight syntax in Hugo but the preferred approach for blogdown is to use Highlight.js. Interestingly, Yi Hui himself is not too particular about the specifics nor the excessiveness of syntax highlighting.

Themes with embedded syntax highlight feature

Some hugo themes have in built syntax highlight functions. For instances, blogdown’s default theme, hugo-lithium, has Highlight.js option readily avilable.

For the hugo-lithium theme, you can access details of the Highlight.js in the config.toml file.

highlightjsVersion = "9.12.0"
highlightjsCDN = "//cdnjs.cloudflare.com/ajax/libs"
highlightjsLang = ["r", "yaml"]
highlightjsTheme = "github"

highlightjsVersion refers to the version of highlightjs

highlightjsCDN refers to the CDN provider of highlight.js. For each CDN provider and version number, you can determine if the coding language you intend to highlight and the style of the highlight is available.

highlightjsLang refers to the coding languages to be highlighted. By default, r and yaml are highlighted. You can add other languages to be highlighted as long as the CDN provider and version number supports the highlighting of those languages.

highlightjsTheme refers to the colour theme for the highlighted syntax. You can preview the various themes for different languages on [highlightjs]’s website before deciding which theme to adopt for your own site. (https://highlightjs.org/static/demo/)

Themes without embedded syntax highlight feature

There are many themes which do not have in built highlighting functions including the Mainroad theme which I’m using. There are two approaches to add syntax highlighting for these Hugo themes.

blogdown textbook approach

  1. In the book, Xie, Thomas and Hill recommends adding
<link href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css" rel="stylesheet">

to head_custom.html file. For the Mainroad theme, I added the script to the bottom of head.html file. You can change the colour theme by replacing the github theme to your desired theme.

  1. Next, they require you to add
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/languages/r.min.js"></script>

<script>
hljs.configure({languages: []});
hljs.initHighlightingOnLoad();
</script>

to foot_custom.html. For the Mainroad theme, I added the script to the bottom of footer.html file.

Amber Thomas’s approach

  1. Download Highlight.js for R.

  2. From the file you downloaded, copy highlight.pack.js file and paste into the js folder for your Hugo theme. For Mainroad theme, I accessed it via themes-> Mainroad-> static-> js.

  3. From the file you downloaded, go to the style subfolder and copy the css file of your desired syntax colour theme and paste into the css folder for your Hugo theme. For Mainroad theme, I found it via themes-> Mainroad -> static -> css.

  4. Add this
<link rel="stylesheet" href="{{"css/github-gist.css" | absURL}}" rel="stylesheet" id="theme-stylesheet">
<script src="{{ "js/highlight.pack.js" | absURL }}"></script>
<script>hljs.initHighlightingOnLoad();</script>

to the header.html file. For Mainroad theme, I discovered the file via themes-> Mainroad-> layouts -> partials. You can change the github-gist theme to your selected theme. As the Hugo Mainroad theme displays code chunks in a faint shade of grey, I chose routeros highlighter as it has a similar light grey as its background which complements the Hugo Mainroad theme.

Verify syntax highlighting

Apart from visually see the changes on your site, you can go geek mode and verify that the highlighted syntax is based on your selected Highlight.js theme. If you are using, Microsoft Edge select a paragraph of plain text and click on the right hand mouse and select “Inspect element”. You will see two boxes. Examine the box which has style as one of the sub-tab. From that sub-tab, you will noticed that the css style is css.style. Now do the same for a chuck of R script, you will realize that the css style is the name of the Highlight.js theme. For this blog, it is routeros.css.