Syntax Highlighting

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:

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

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. Note that this option is not relevant when pygmentsUseClasses is set.

Syntax highlighting galleries: Chroma (short snippets, long snippets), Pygments

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

{{< highlight html >}}
<section id="main">
  <div>
    <h1 id="title">{{ .Title }}</h1>
    {{ range .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;

```go-html-template
<section id="main">
  <div>
    <h1 id="title">{{ .Title }}</h1>
    {{ range .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 highlight template func or when doing highlighting in code fences):

ABNF

abnf

ANTLR

antlr

APL

apl

ActionScript

actionscript, as

ActionScript 3

actionscript3, as, as3

Ada

ada, ada2005, ada95, adb, ads

Angular2

ng2

ApacheConf

aconf, apache, apacheconf, conf, htaccess

AppleScript

applescript

Awk

awk, gawk, mawk, nawk

BNF

bnf

Ballerina

bal, ballerina

Base Makefile

*, bsdmake, mak, make, makefile, mf, mk

Bash

bash, bash_*, bashrc, ebuild, eclass, exheres-0, exlib, ksh, sh, shell, zsh, zshrc

Batchfile

bat, batch, cmd, dosbatch, winbatch

BlitzBasic

b3d, bb, blitzbasic, bplus, decls

Brainfuck

b, bf, brainfuck

C

c, h, idc

C#

c#, cs, csharp

C++

C, CPP, H, c++, cc, cp, cpp, cxx, h++, hh, hpp, hxx

CFEngine3

cf, cf3, cfengine3

CMake

cmake, txt

COBOL

COB, CPY, cob, cobol, cpy

CSS

css

Cap'n Proto

capnp

Cassandra CQL

cassandra, cql

Ceylon

ceylon

ChaiScript

chai, chaiscript

Cheetah

cheetah, spitfire, spt, tmpl

Clojure

clj, clojure

CoffeeScript

coffee, coffee-script, coffeescript

Common Lisp

cl, common-lisp, lisp

Coq

coq, v

Crystal

cr, crystal

Cython

cython, pxd, pxi, pyrex, pyx

DTD

dtd

Dart

dart

Diff

diff, patch, udiff

Django/Jinja

django, jinja

Docker

docker, dockerfile

EBNF

ebnf

Elixir

elixir, ex, exs

Elm

elm

EmacsLisp

el, elisp, emacs, emacs-lisp

Erlang

erl, erlang, es, escript, hrl

FSharp

fs, fsharp, fsi

Factor

factor

Fish

fish, fishshell, load

Forth

forth, frt, fs

Fortran

F03, F90, f03, f90, fortran

GAS

S, asm, gas, s

GDScript

gd, gdscript

GLSL

frag, geo, glsl, vert

Genshi

genshi, kid, xml+genshi, xml+kid

Genshi HTML

html+genshi, html+kid

Genshi Text

genshitext

Gnuplot

gnuplot, plot, plt

Go

go, golang

Go HTML Template

go-html-template

Go Text Template

go-text-template

Groovy

gradle, groovy

HTML

htm, html, xhtml, xslt

HTTP

http

Handlebars

handlebars

Haskell

haskell, hs

Haxe

haxe, hx, hxsl

Hexdump

hexdump

Hy

hy, hylang

INI

cfg, dosini, gitconfig, inf, ini

Idris

idr, idris

Io

io

JSON

json

JSX

jsx, react

Java

java

JavaScript

javascript, js, jsm

Julia

jl, julia

Jungle

jungle

Kotlin

kotlin, kt

LLVM

ll, llvm

Lighttpd configuration file

lighttpd, lighty

Lua

lua, wlua

Mako

mako, mao

Mason

m, mason, mc, mhtml, mi

Mathematica

cdf, ma, mathematica, mma, nb, nbp

MiniZinc

MZN, dzn, fzn, minizinc, mzn

Modula-2

def, m2, mod, modula2

MonkeyC

mc, monkeyc

MorrowindScript

morrowind, mwscript

MySQL

mysql, sql

Myghty

myghty, myt

NASM

ASM, asm, nasm

Newspeak

newspeak, ns2

Nginx configuration file

conf, nginx

Nim

nim, nimrod

Nix

nix, nixos

OCaml

ml, mli, mll, mly, ocaml

Objective-C

h, m, obj-c, objc, objective-c, objectivec

Octave

m, octave

OpenSCAD

openscad, scad

Org Mode

org, orgmode

PHP

inc, php, php3, php4, php5, php[345]

PL/pgSQL

plpgsql

POVRay

inc, pov

PacmanConf

conf, pacmanconf

Perl

perl, pl, pm, t

Pig

pig

PkgConfig

pc, pkgconfig

PostScript

eps, postscr, postscript, ps

PostgreSQL SQL dialect

postgres, postgresql

PowerShell

posh, powershell, ps1, psm1

Prolog

ecl, pl, pro, prolog

Protocol Buffer

proto, protobuf

Puppet

pp, puppet

Python

py, python, pyw, sage, sc, tac

Python 3

py3, python3

QBasic

BAS, bas, basic, qbasic

R

R, Renviron, Rhistory, Rprofile, S, r, s, splus

Racket

racket, rkt, rktd, rktl

Ragel

ragel

Rexx

arexx, rex, rexx, rx

Ruby

duby, gemspec, rake, rb, rbw, rbx, ruby

Rust

in, rs, rust

SCSS

scss

SPARQL

rq, sparql

SQL

sql

SYSTEMD

service, systemd

Sass

sass

Scala

scala

Scheme

scheme, scm, ss

Scilab

sce, sci, scilab, tst

Smalltalk

smalltalk, squeak, st

Smarty

smarty, tpl

Snobol

snobol

Solidity

sol, solidity

SquidConf

conf, squid, squid.conf, squidconf

Swift

swift

TASM

ASM, asm, tasm

TOML

toml

Tcl

rvt, tcl

Tcsh

csh, tcsh

TeX

aux, latex, tex, toc

Termcap

src, termcap

Terminfo

src, terminfo

Terraform

terraform, tf

Thrift

thrift

TradingView

tradingview, tv

Transact-SQL

t-sql, tsql

Turtle

ttl, turtle

Twig

twig

TypeScript

ts, tsx, typescript

TypoScript

ts, txt, typoscript

TypoScriptCssData

typoscriptcssdata

TypoScriptHtmlData

typoscripthtmldata

VHDL

vhd, vhdl

VimL

exrc, gvimrc, vim, vimrc

WDTE

wdte

XML

rss, svg, wsdl, wsf, xml, xsd, xsl, xslt

Xorg

conf, xorg.conf

YAML

yaml, yml

cfstatement

cfs

markdown

markdown, md, mkd

plaintext

no-highlight, plain, text, txt

reStructuredText

rest, restructuredtext, rst

reg

reg, registry

systemverilog

sv, svh, systemverilog

verilog

v, verilog

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.

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.