Harry Cresswell

Performant syntax highlighting in Hugo

The quickest way to use syntax highlighting in Hugo is with Chroma, the default syntax highlighter. Without any config, you can wrap a code block in the built in highlight Shortcode, pass in the language as a variable and you’re code will be highlighted:

{< highlight go >}
	// Html code to highlight
{< / highlight >}

Note: to render the example above on the page I have used single curly braces. You will need to use double curly braces.

The advantage of using Chroma over other JavaScript libraries like Highlight.js or Prisma.js is that it’s built right into Hugo and doesn’t require any external dependencies. This make it extremely fast and reliable.

Out of the box, however, Chroma doesn’t give us much control over the style of our highlighted code. To change that all we need to do is add one line of code to the top level of our config.toml file:

# Enable for syntax highlighting
pygmentsUseClasses = true

Note: It’s important you add this line to the top level and not under [params] if you want it to work. Something like this should do it:

baseurl = "http://localhost:1313/"
theme="theme name"
languageCode = "en"
title = "your site title"

# Enable for syntax highlighting
pygmentsUseClasses = true

Adding option for code fencing #

It is also possible to add syntax highlighting to code within code fences. To enable this add the following to your config.toml file:

pygmentsCodefences = true

Now you can wrap your code in two sets of triple backticks (```) and specify the language after the opening set to highlight the code correctly. Make sure you check the list of supported langauges.

(```) yaml
pygmentsUseClasses = true
pygmentsCodeFences = true
(```)

Note: Make sure you omit the parentheses as seen above. This is just to show you the code without it rendering.

Now you can highlight any syntax inside of code fences:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>Hello, world!</title>
  </head>
  <body>
    <h1>Hello, world!</h1>
  </body>
</html>

Customising your syntax theme #

To change the theme of your syntax highlighting generate chromastyles. Then set the name of the theme you want using the --style flag.

From the command line run:

hugo gen chromastyles --style=lovelace > syntax.css

This will generate the syntax.css file at the root of your project.

See https://xyproto.github.io/splash/docs/ for available themes. You can also run hugo gen chromastyles -h to see more options.

Don’t forget to link to the stylesheet from the of your document otherwise your theme won’t work!

Weekly Newsletter

Braintactics is a weekly roundup of articles, tools and tips for product designers and front-end developers. I send it every Friday morning.