Syntax highlighting

Hugo uses Chroma as its code highlighter; it is built in Go and is really, really fast.

Configure syntax highlighter #

See Configure Highlight.

Generate syntax highlighter CSS #

If you run with markup.highlight.noClasses=false in your site configuration, you need a style sheet. The style sheet will override the style specified in markup.highlight.style.

You can generate one with Hugo:

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

Run hugo gen chromastyles -h for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles.

Highlight shortcode #

Highlighting is carried out via the built-in highlight shortcode. It takes exactly one required argument for the programming language to be highlighted and requires a closing tag.

Options:

• linenos: configure line numbers. Valid values are true, false, table, or inline. false will turn off line numbers if it’s configured to be on in site configuration. table will give copy-and-paste friendly code blocks.
• hl_lines: lists a set of line numbers or line number ranges to be highlighted.
• linenostart=199: starts the line number count from 199.
• anchorlinenos: Configure anchors on line numbers. Valid values are true or false;
• lineanchors: Configure a prefix for the anchors on line numbers. Will be suffixed with -, so linking to the line number 1 with the option lineanchors=prefix adds the anchor prefix-1 to the page.
• hl_inline Highlight inside a <code> (inline HTML element) tag. Valid values are true or false. The code tag will get a class with name code-inline.

Example: highlight shortcode #

{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}}
// ... code
{{< / highlight >}}

Gives this:

199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

// GetTitleFunc returns a func that can be used to transform a string to
// title case.
//
// The supported styles are
//
// - "Go" (strings.Title)
// - "AP" (see https://www.apstylebook.com/)
// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
//
// If an unknown or empty style is provided, AP style is what you get.
func GetTitleFunc(style string) func(s string) string {
  switch strings.ToLower(style) {
  case "go":
    return strings.Title
  case "chicago":
    return transform.NewTitleConverter(transform.ChicagoStyle)
  default:
    return transform.NewTitleConverter(transform.APStyle)
  }
}

Highlight Hugo/Go template code #

For highlighting Hugo/Go template code on your page, add /* after the opening double curly braces and */ before closing curly braces.

{{</* myshortcode */>}}

Gives this:

{{< myshortcode >}}

Highlight template function #

See Highlight.

Highlighting in code fences #

Highlighting in code fences is enabled by default.

```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
// ... code
```

Gives this:

199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

// GetTitleFunc returns a func that can be used to transform a string to
// title case.
//
// The supported styles are
//
// - "Go" (strings.Title)
// - "AP" (see https://www.apstylebook.com/)
// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
//
// If an unknown or empty style is provided, AP style is what you get.
func GetTitleFunc(style string) func(s string) string {
  switch strings.ToLower(style) {
  case "go":
    return strings.Title
  case "chicago":
    return transform.NewTitleConverter(transform.ChicagoStyle)
  default:
    return transform.NewTitleConverter(transform.APStyle)
  }
}

The options are the same as in the highlighting shortcode, including linenos=false, but note the slightly different Markdown attribute syntax.

List of Chroma highlighting languages #

The full list of Chroma lexers and their aliases (which is the identifier used in the highlight template func or when doing highlighting in code fences):