Syntax Highlighting

Hugo uses Chroma as its code highlighter; it is built in Go and is really, really fast – and for the most important parts compatible with Pygments we used before.

Configure Syntax Highlighter

See Configure Highlight.

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.

Options:

linenos: Valid values are true, false, table, inline. table will give copy-and-paste friendly code blocks) turns on line numbers.
Setting linenos to false will turn off linenumbers if it’s configured to be on in site config.
hl_lines lists a set of line numbers or line number ranges to be highlighted.
linenostart=199 starts the line number count from 199.

Example: Highlight Shortcode

{{< 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
// 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":
    return transform.NewTitleConverter(transform.ChicagoStyle)
  default:
    return transform.NewTitleConverter(transform.APStyle)
  }
}

Highlight Template Func

See Highlight.

Highlighting in Code Fences

Highlighting in code fences is enabled by default.

```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
// ... code
```

Gives this:

199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
// 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":
    return transform.NewTitleConverter(transform.ChicagoStyle)
  default:
    return transform.NewTitleConverter(transform.APStyle)
  }
}

Note that only Goldmark supports passing attributes such as hl_lines, and it’s important that it does not contain any spaces. See goldmark-highlighting for more information.

The options are the same as in the highlighting shortcode,including linenos=false, but note the slightly different Markdown attribute syntax.

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):

ABAP: ABAP, abap
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
BibTeX: bib, bibtex
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, fth
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
Igor: igor, igorpro, ipf
Io: io
J: ijs, j
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
MLIR: mlir
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
Standard ML: fun, sig, sml
Swift: swift
TASM: ASM, asm, tasm
TOML: toml
TableGen: tablegen, td
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