hugo/docs/content/en/content-management/syntax-highlighting.md
Bjørn Erik Pedersen bfb9613a14
Add Goldmark as the new default markdown handler
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo.

If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration:

```toml
[markup]
defaultMarkdownHandler="blackfriday"
```

Fixes #5963
Fixes #1778
Fixes #6355
2019-11-23 14:12:24 +01:00

4.7 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 pygmentsUseClasses=true 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 shortcode highlight. highlight 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: Valid values are true, false, table, inline. table will give copy-and-paste friendly code blocks) turns on line numbers.
  • Setting linenos to false will turn off linenumbers if it's configured to be on in site config.{{< new-in "0.60.0" >}}
  • hl_lines lists a set of line numbers or line number ranges to be highlighted.
  • linenostart=199 starts the line number count from 199.

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": tc := transform.NewTitleConverter(transform.ChicagoStyle) return tc.Title default: tc := transform.NewTitleConverter(transform.APStyle) return tc.Title } } {{< / highlight >}}

Highlight Template Func

See Highlight.

Highlighting in Code Fences

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

```go-html-template{hl_lines=[3,"5-6"],linenos=true}
```
```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 219 220 // 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": tc := transform.NewTitleConverter(transform.ChicagoStyle) return tc.Title default: tc := transform.NewTitleConverter(transform.APStyle) return tc.Title } }

{{< 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 >}}