hugo/content/content-management/syntax-highlighting.md
Bjørn Erik Pedersen 05e42bc643 Squashed 'docs/' changes from e65df1059..a042b67b5
a042b67b5 Update installation instructions for Fedora, CentOS, Red Hat
e99dcb0b5 Document `:sections` placeholder for permalinks
f33c88a27 Fix and clarify documentation about Blackfriday extensions (mask)
5cab109c2 Add .Page.File documentation
62df7bb80 Add .Page.CurrentSection and .Page.Sections documentation
60b4414de Add .Page.Dir documentation
22038d1a8 shortcode-templates.md: Update year example
850d5ca41 Add note about theme versions in hosting-on-netlify.md
0509b8055 Update permalink example URL
c68d61d3a Mention the available 'width' argument in 'figure' shortcode
ed83b483a Update Nanobox deployment tutorial
a7422f35d shortcode-templates.md: Remove stray period
af2905fe4 Fix order of releases in news section
19d3ea064 Bump to 0.30.2
bbfa10343 Merge branch 'next'
36ed7cbe4 releaser: Prepare repository for 0.31-DEV
f689770f6 releaser: Add release notes to /docs for release of 0.30.2
0045e712a releaser: Bump versions for release of 0.30.2
a9efc3bbd Add slug to 0.30.1 relnotes
9cf47a4a1 Release 0.30.1
1fa0bb23d releaser: Prepare repository for 0.31-DEV
5582208b6 releaser: Add release notes to /docs for release of 0.30.1
09693d155 releaser: Bump versions for release of 0.30.1
58adf5d0d Merge commit '325009c3fd4ac90021897b7e3e025c14e70ce162'
4ef5dcb9b releaser: Prepare repository for 0.31-DEV
02938a788 releaser: Add release notes to /docs for release of 0.30.1
7cfd01fc6 releaser: Bump versions for release of 0.30.1
db3a68e24 Fix typo
95a5d8b46 Fix format of summaryLength in TOML example config
2ad649a92 Make terms in taxonomy examples more coherent
1fac1e662 Make a link specifically point to Pygments HTML Formatter docs
11ae6be03 Fix minor typos in v0.30 release notes

git-subtree-dir: docs
git-subtree-split: a042b67b5b8834ee8292849708cba724f5d6644e
2017-11-17 13:46:40 +01:00

188 lines
6.8 KiB
Markdown

---
title: Syntax Highlighting
description: Hugo comes with reallly fast syntax highlighting from Chroma.
date: 2017-02-01
publishdate: 2017-02-01
keywords: [highlighting,pygments,chroma,code blocks,syntax]
categories: [content management]
menu:
docs:
parent: "content-management"
weight: 300
weight: 20
sections_weight: 20
draft: false
aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
toc: true
---
From Hugo 0.28, the default syntax hightlighter in Hugo is [Chroma](https://github.com/alecthomas/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](#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 Hightlighter
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](#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](http://pygments.org/docs/formatters/#HtmlFormatter) 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:
```bash
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](/content-management/shortcodes/) `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 */>}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{</* /highlight */>}}
{{< /code >}}
## Highlight Template Func
See [Highlight](/functions/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](/getting-started/configuration/);
````
```html
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
```
````
## 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](https://www.python.org/downloads/). 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`.
[Prism]: http://prismjs.com
[prismdownload]: http://prismjs.com/download.html
[Highlight.js]: http://highlightjs.org/
[Rainbow]: http://craig.is/making/rainbows
[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/
[Google Prettify]: https://github.com/google/code-prettify
[Yandex]: http://yandex.ru/