hugo/content/en/content-management/syntax-highlighting.md
Bjørn Erik Pedersen d2b1030060 Squashed 'docs/' changes from e161ea09d..0fd7b4169
0fd7b4169 Fix typo: pygmentsUseClasses -> pygmentsUseClassic
9a3e1c19a Clarify that lower weight gets higher precedence
820d8b581 Clarify the true behavior of hrefTargetBlank #blackfriday
eb3aa5e46 Fix typo
9aedb9269 Add examples for removing default taxonomies
772a26f84 Fix source link on maintainance
975c215ae Minor edits.
2bdb1a150 Fix invalid iink
991d2e139 Fix misspelling
60af8dfb0 Update eSolia link
d7426b76e Release 0.40.3
4977bd9cf Merge branch 'release-0.40.3'
9946f7108 releaser: Prepare repository for 0.41-DEV
beef16b01 releaser: Add release notes to /docs for release of 0.40.3
80c51c55a releaser: Bump versions for release of 0.40.3
21e2934c5 rename `taxonomies.html` to `taxonomy.html`
34a02c289 Add release notes from Hugo 0.7 to 0.15 for completeness
b593f512e Update related.md
7c2bf528b Fix the "edit this page" link
e8fbc163e Add warning about cond
ae15a8831 Add link to Markdown Guide
e077dfd65 Added documentation for a new migration tool: BlogMl2Hugo
957bfb6a8 Add Talkayrd, a new commenting system, & fix txtpen link
86acea7f8 Tomango showcase
3c2fc32f1 Fix snap classic command in installing.md
9a76f1737 Merge commit '83bef6955e014d40c0f00db9cebe09113154e999'
a4b71fb84 Fix typo

git-subtree-dir: docs
git-subtree-split: 0fd7b416997bf76cd99e3ae2dfae406cb8b6724a
2018-05-25 15:04:07 +02:00

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
pygments
chroma
code blocks
syntax
content management
docs
parent weight
content-management 300
20 20 false
/extras/highlighting/
/extras/highlight/
/tools/syntax-highlighting/
true

From Hugo 0.28, the default syntax hightlighter in Hugo is Chroma; it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments.

If you want to continue to use Pygments (see below), set pygmentsUseClassic=true in your site config.

The example below shows a simple code snippet from the Hugo source highlighted with the highlight shortcode. Note that the gohugo.io site is generated with pygmentsUseClasses=true (see Generate Syntax Highlighter CSS).

  • linenos=inline or linenos=table (table will give copy-and-paste friendly code blocks) turns on line numbers.
  • hl_lines lists a set of line numbers or line number ranges to be highlighted. Note that the hyphen range syntax is only supported for Chroma.
  • linenostart=199 starts the line number count from 199.

With that, this:

{{</* 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 http://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 >}}

Configure Syntax Highlighter

To make the transition from Pygments to Chroma seamless, they share a common set of configuration options:

pygmentsOptions
A comma separated list of options. See below for a full list.
pygmentsCodefences
Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example).
pygmentsStyle
The style of code highlighting. See https://help.farbox.com/pygments.html for a gallery. Note that this option is not relevant when pygmentsUseClasses is set.
pygmentsUseClasses
Set to true to use CSS classes to format your highlighted code. See Generate Syntax Highlighter CSS.
pygmentsCodefencesGuessSyntax
Set to true to try to do syntax highlighting on code fenced blocks in markdown without a language tag.
pygmentsUseClassic
Set to true to use Pygments instead of the much faster Chroma.

Options

pygmentsOptions can be set either in site config or overridden per code block in the Highlight shortcode or template func.

noclasses
Use inline style.
linenos
For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control.
linenostart
Start the line numbers from this value (default is 1).
hl_lines
Highlight a space separated list of line numbers. For Chroma, you can provide a list of ranges, i.e. "3-8 10-20".

The full set of supported options for Pygments is: encoding, outencoding, nowrap, full, title, style, noclasses, classprefix, cssclass, cssstyles, prestyles, linenos, hl_lines, linenostart, linenostep, linenospecial, nobackground, lineseparator, lineanchors, linespans, anchorlinenos, startinline. See the Pygments HTML Formatter Documentation for details.

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://help.farbox.com/pygments.html 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.

Example highlight Shortcode

{{< code file="example-highlight-shortcode-input.md" >}} {{</* highlight html */>}}

{{ .Title }}

{{ range .Data.Pages }} {{ .Render "summary"}} {{ end }}
{{}} {{< /code >}}

Highlight Template Func

See Highlight.

Highlight in Code Fences

It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the pygmentsCodeFences to true in Hugo's configuration file;

```go-html-template
<section id="main">
  <div>
    <h1 id="title">{{ .Title }}</h1>
    {{ range .Data.Pages }}
      {{ .Render "summary"}}
    {{ end }}
  </div>
</section>
```

List of Chroma Highlighting Languages

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

{{< chroma-lexers >}}

Highlight with Pygments Classic

If you for some reason don't want to use the built-in Chroma highlighter, you can set pygmentsUseClassic=true in your config and add Pygments to your path.

{{% note "Disclaimers on Pygments" %}}

  • Pygments is relatively slow and causes a performance hit when building your site, but Hugo has been designed to cache the results to disk.
  • The caching can be turned off by setting the --ignoreCache flag to true.
  • The languages available for highlighting depend on your Pygments installation. {{% /note %}}

If you have never worked with Pygments before, here is a brief primer:

  • Install Python from python.org. Version 2.7.x is already sufficient.
  • Run pip install Pygments in order to install Pygments. Once installed, Pygments gives you a command pygmentize. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it.

On Debian and Ubuntu systems, you may also install Pygments by running sudo apt-get install python3-pygments.