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!