HUGO

  • News
  • Docs
  • Themes
  • Community
  • GitHub
Star

What's on this Page

    • Configure Syntax Hightlighter
      • Options
    • Generate Syntax Highlighter CSS
    • Highlight Shortcode
      • Example highlight Shortcode
    • Highlight Template Func
    • Highlight in Code Fences
    • Highlight with Pygments Classic
CONTENT MANAGEMENT

Syntax Highlighting

Hugo comes with reallly fast syntax highlighting from Chroma.

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 turns on line numbers. Note that the inline value only has an effect in Pygments.
  • 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=inline,hl_lines=8 15-17,linenostart=199" >}}
// ... code
{{< / highlight >}}

Gives this:

199// GetTitleFunc returns a func that can be used to transform a string to
200// title case.
201//
202// The supported styles are
203//
204// - "Go" (strings.Title)
205// - "AP" (see https://www.apstylebook.com/)
206// - "Chicago" (see http://www.chicagomanualofstyle.org/home.html)
207//
208// If an unknown or empty style is provided, AP style is what you get.
209func GetTitleFunc(style string) func(s string) string {
210  switch strings.ToLower(style) {
211  case "go":
212    return strings.Title
213  case "chicago":
214    tc := transform.NewTitleConverter(transform.ChicagoStyle)
215    return tc.Title
216  default:
217    tc := transform.NewTitleConverter(transform.APStyle)
218    return tc.Title
219  }
220}

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.
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 Documentation for details.

Generate Syntax Highlighter CSS

If you run with pygmentsUseClassic=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

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

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;

```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.

  • 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.

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.

See Also

  • highlight
  • About Hugo
    • Overview
    • Hugo Features
    • The Benefits of Static
    • Roadmap
    • License
  • Getting Started
    • Get Started Overview
    • Quick Start
    • Install Hugo
    • Basic Usage
    • Directory Structure
    • Configuration
  • Themes
    • Themes Overview
    • Install and Use Themes
    • Customize a Theme
    • Create a Theme
  • Content Management
    • Content Management Overview
    • Organization
    • Supported Content Formats
    • Front Matter
    • Shortcodes
    • Related Content
    • Sections
    • Types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and Cross References
    • URL Management
    • Menus
    • Table of Contents
    • Comments
    • Multilingual and i18n
    • Syntax Highlighting
  • Templates
    • Templates Overview
    • Introduction
    • Template Lookup Order
    • Custom Output Formats
    • Base Templates and Blocks
    • List Page Templates
    • Homepage Template
    • Section Templates
    • Taxonomy Templates
    • Single Page Templates
    • Content View Templates
    • Data Templates
    • Partial Templates
    • Shortcode Templates
    • Local File Templates
    • 404 Page
    • Menu Templates
    • Pagination
    • RSS Templates
    • Sitemap Template
    • Robots.txt
    • Internal Templates
    • Alternative Templating
    • Template Debugging
  • Functions
    • Functions Quick Reference
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .Param
    • .Scratch
    • .Unix
    • Math
    • absLangURL
    • absURL
    • after
    • apply
    • base64
    • chomp
    • countrunes
    • countwords
    • dateFormat
    • default
    • delimit
    • dict
    • echoParam
    • emojify
    • eq
    • findRE
    • first
    • ge
    • getenv
    • gt
    • hasPrefix
    • highlight
    • htmlEscape
    • htmlUnescape
    • humanize
    • i18n
    • imageConfig
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • lang.NumFmt
    • last
    • le
    • lower
    • lt
    • markdownify
    • md5
    • ne
    • now
    • partialCached
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • relLangURL
    • relURL
    • relref
    • render
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeURL
    • seq
    • sha
    • shuffle
    • singularize
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • time
    • title
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urls.Parse
    • where
    • with
  • Variables
    • Variables Overview
    • Site Variables
    • Page Variables
    • Shortcode Variables
    • Taxonomy Variables
    • File Variables
    • Menu Variables
    • Hugo Variables
    • Git Variables
    • Sitemap Variables
  • CLI
  • Troubleshooting
    • Troubleshoot
    • Accented Characters in URLs
    • Build Performance
    • EOF Error
  • Tools
    • Developer Tools Overview
    • Migrations
    • Starter Kits
    • Frontends
    • Editor Plug-ins
    • Search
    • Other Projects
  • Hosting & Deployment
    • Hosting & Deployment Overview
    • Host-Agnostic Deploys with Nanobox
    • Host on Netlify
    • Host on Firebase
    • Host on GitHub
    • Host on GitLab
    • Host on Bitbucket
    • Deployment with Wercker
    • Deployment with Rsync
  • Contribute
    • Contribute to Hugo
    • Development
    • Documentation
    • Themes
“Syntax Highlighting” was last updated: October 13, 2017: Initial commit (a48229f)
Improve this page
By the Hugo Authors

The Hugo logos are copyright © Steve Francia 2013–2017.

The Hugo Gopher is based on an original work by Renée French.

  • File an Issue
  • Get Help
  • Discuss the Source Code
  • @GoHugoIO
  • @spf13
  • @bepsays
  • News
  • Docs
  • Themes
  • Community
  • GitHub
  • About Hugo
  • Getting Started
  • Themes
  • Content Management
  • Templates
  • Functions
  • Variables
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute