Adding Prism.js Code Highlighting to Hugo (or any other markdown based site)

Adding a code highlighter is a really nice way to both show code on your site in a more decorative way, but also to make it easier for users to reproduce what you may be asking them to do. I recently (around February) rebuilt my Drupal site into Hugo and when migrating the content, one of the core things I wanted to do was get really nice highlighting of code, especially as I use my blog to remember things that I was doing 2, 3, 4, 5 years ago.

Hugo has the ability to use Chroma included in core, however, I wanted to use Prism.js due to what I thought were nicer included themes and the ability to easily display command-line output. I am not bashing Chroma, just I sometimes like different things.

Setting up Prism.js

As you can probably see from the Prism.js website, you have a range of themes, syntaxes and plugins that you can use. For my own uses I only included the ability to highlight the languages that I regularly (or semi-regularly) use, including; HTML (+ XML), CSS, JavaScript, C-like, SQL, Bash + Shell, Django/Jinja2, Python, PHP, Go, Git, Docker, nginx, SCSS, SASS, YAML, TOML, ini. I also added in the Tomorrow Night theme and some plugins; Line Numbers, Autolinker and Command Line. You could even download the same as me using this link https://prismjs.com/download.html#themes=prism-tomorrow&languages=markup+css+clike+javascript+bash+ruby+markup-templating+docker+git+go+ini+php+json+django+nginx+sql+scss+python+sass+yaml+toml&plugins=line-numbers+autolinker+command-line.

Add Prism.js JavaScript and CSS to your site

For every page that you want to use the code-highlighting, you need to have the downloaded JS and CSS inside the site. I am going to make the assumption that most of you would know how to do this but here is a simple example. For me these go into the following:

`layouts/partials/header.html`

<head>
    ...
    <link rel='stylesheet' href='/css/prism.css' />
</head>
<body>

`layouts/partials/footer.html`

    ...
    <script src='/js/prism.js'></script>
</body>
</html>

When each page is built by Hugo, these partials are used to complete the head and footer of each page therefore including Prism.js JS and CSS for use everywhere!

Using Code Highlighting in Markdown

Generally speaking writing code in markdown uses three backticks (`) however to get the value of highlighting you need to tell it what language you are using. These are examples using the following:

```html

<a href="/link.html" title="I am a link">
    <img src="image.jpg" alt="An example image" />
</a>

```python

# Import the modules
import sys
import random

ans = True

while ans:
    question = raw_input("Ask the magic 8 ball a question: (press enter to quit) ")
    answers = random.randint(1,8)

    if question == "":
        sys.exit()

```docker

FROM willhallonline/ansible:latest

RUN ansible-playbook -i localhost playbook.yml

CMD["ansible-playbook"]

Command Line Highlighting

One of my favourite parts of Prism.js is the ability to show command line output in a nice way. This is something that I have struggled with for a long-time because so much of what I do (and enjoy doing) is on command line, but the output can be a little difficult to judge. Prism.js with the command-line plugin gets around this by adding data to the <pre> html and then using it to format the output. So whereas just using bash on some output may look like this:

$ df -h
Filesystem               Size  Used Avail Use% Mounted on
udev                     7.6G     0  7.6G   0% /dev
tmpfs                    1.6G  2.2M  1.6G   1% /run
/dev/nvme0n1p1           454G  147G  285G  34% /
tmpfs                    1.6G   48K  1.6G   1% /run/user/1000
/home/willhall/.Private  454G  147G  285G  34% /home/willhall
/dev/fuse                250G   512  250G   1% /run/user/1000/keybase/kbfs

With the command-line formatter I get it to look like this:

However, this is not without issue as Markdown does not have easy ways to be able to put in extra data to your html so, this has to replace the backticks with something far less beautiful; <pre class="command-line language-bash" data-user="willhall" data-host="ubuntu" data-output="2-8"><code class="language-bash">, and end your output with closing html tags </code></pre>. However, I am sure you will agree the output is far easier to read and understand, so I guess it is a necessary evil. You can get more detail about using the plugin on the Prism.js command-line plugin page.

In Summary of Prism.js

So, as an overall summary, I have been really pleased with using Prism.js for code highlighting and even happier using it to style command-line output.