How to Add Syntax Highlighting to Your Hugo Post Markdown

Syntax highlighting in Hugo post markdown - a short(ish) guide

This post extends on a previous blog post looking at adding some base css styles to <code> elements in markdown.

Adding syntax highlighting to <code> blocks is a really nice feature for any blog and makes the key content MUCH easier to take in. Syntax highlighting helps with the work of building the mental of model of the code being read.

Adding syntax highlighting to post markdown is another feature that Hugo handles really beautifully out of the box.

Read about syntax highlighting in Hugo.

Basically, out of the box hugo ships with a series of shortcodes that you can use in your markdown that hook into Chroma during build time. These shortcodes can handle syntax highlighting for nearly every use case.

For a lot of blogs the out of the box setup for syntax highlighting will work just fine, so all you really need to do now is get familiar with the shortcode that hugo gives us.

Read about the highlight shortcode.

An example of how to use the highlight shortcode to higlight some template code which has some go-template syntax with some html markup.

{{/*< highlight go-html-template >*/}}
    {{ $home := $.IsHome}}
    {{- range $item := . }}
        <li class="navigation-item">
        {{ if eq $.Name $item.Name }}
            <a aria-current="page" class="navigation-link navigation-link--current" href="{{ $item.URL }}">{{ $item.Name}}</a>
        {{ else if (and ($home) (eq $item.URL "/"))}}
            <a aria-current="page" class="navigation-link navigation-link--current" href="{{ $item.URL }}">{{ $item.Name}}</a>
        {{ else }}
            <a aria-current="false" class="navigation-link" href="{{ $item.URL }}">{{ $item.Name }}</a>
        {{ end }}
        </li>
    {{- end }}
{{/*< / highlight >*/}}

Notice the use of the highlight keyword, followed by stating what syntax the highlighter should expect. In this case it’s go-html-template. Overall, thats a really nice way to syntax highlight any code you’d like to render on your posts.

On the front-end, this default output will inline styles to the <code> elements using the monokai css theme which is a popular style guide for code-editors.

For smaller and more simple code blocks, you can also use the syntax highlight feature available from extended markdown.

```toml
baseURL = 'https://hugo-theme-spaced-blog.luke-morgan.com/'
languageCode = 'en-us'
title = 'Spaced Blog'
theme = 'spaced-blog'
paginate = 5

How to use custom syntax highlighting styles.

For my use case for this blog, I was really happy with most of the monokai styles, but the inline background color that gets added to all block level <code> markup wasn’t working for my design.

The first thing you need to do is tell the markup generator to use css classes for highlighting as opposed to inline styles.

[markup]
  [markup.highlight]
    noClasses = false

Now you can either create a custom stylesheet from scratch, or like me generate a stylesheet and just modify it slightly.

One again, Hugo has something for this ready to go: Read about generating syntaxt highlighter styles

So in your project, run this:

hugo gen chromastyles --style=monokai > /themes/your-theme/syntax.css

This has just created a ready to go stylesheet using the monokai theme. Include that stylesheet in your layout file and make any edits you want.

  {{ $syntax := resources.Get "css/syntax.css" | resources.Minify | resources.Fingerprint -}}
  <link rel="stylesheet" href="{{ $syntax.RelPermalink }}" />