hugo/docs/content/en/content-management/syntax-highlighting.md
2022-06-28 20:51:33 +02:00

5.1 KiB

title description date publishdate keywords categories menu weight sections_weight draft aliases toc
Syntax Highlighting Hugo comes with really fast syntax highlighting from Chroma. 2017-02-01 2017-02-01
highlighting
chroma
code blocks
syntax
content management
docs
parent weight
content-management 300
20 20 false
/extras/highlighting/
/extras/highlight/
/tools/syntax-highlighting/
true

Hugo uses Chroma as its code highlighter; it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments we used before.

Configure Syntax Highlighter

See Configure Highlight.

Generate Syntax Highlighter CSS

If you run with markup.highlight.noClasses=false in your site config, you need a style sheet.

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 parameter for the programming language to be highlighted and requires a closing shortcode. Note that highlight is not used for client-side javascript highlighting.

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 config. {{< new-in "0.60.0" >}} 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. {{< new-in "0.101.0" >}}

Example: Highlight Shortcode

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

Gives this:

{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}} // 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 >}}

Highlight Template Func

See Highlight.

Highlighting in Code Fences

Highlighting in code fences is enabled by default.{{< new-in "0.60.0" >}}

```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) } }

{{< new-in "0.60.0" >}}Note that only Goldmark supports passing attributes such as hl_lines, and it's important that it does not contain any spaces. See goldmark-highlighting for more information.

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):

{{< chroma-lexers >}}