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
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 |
|
|
|
20 | 20 | false |
|
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
orlinenos=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 }}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 totrue
. - 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 commandpygmentize
. 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
.