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.
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:
<head> ... <link rel='stylesheet' href='/css/prism.css' /> </head> <body>
... <script src='/js/prism.js'></script> </body> </html>
When each page is built by Hugo, these partials are used to complete the
footer of each page therefore including Prism.js JS and CSS for use everywhere!
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:
<a href="/link.html" title="I am a link"> <img src="image.jpg" alt="An example image" /> </a>
# 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()
FROM willhallonline/ansible:latest RUN ansible-playbook -i localhost playbook.yml CMD["ansible-playbook"]
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:
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
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.
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.