CONTENT MANAGEMENT

Syntax Highlighting

From Hugo 0.28, the default syntax highlighter 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 https://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://xyproto.github.io/splash/docs/ 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 .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
Arduino
arduino, ino
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
D
d, di
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
GraphQL
gql, graphql, graphqls
Groovy
gradle, groovy
HCL
hcl
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
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
Matlab
m, matlab
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
Turing
tu, turing
Turtle
ttl, turtle
Twig
twig
TypeScript
ts, tsx, typescript
TypoScript
ts, txt, typoscript
TypoScriptCssData
typoscriptcssdata
TypoScriptHtmlData
typoscripthtmldata
VB.net
bas, vb, vb.net, vbnet
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
react
jsx, react
reg
reg, registry
systemverilog
sv, svh, systemverilog
verilog
v, verilog
vue
vue, vuejs

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.

See Also

“Syntax Highlighting” was last updated: October 24, 2019: remake. (28623dd)
Improve this page