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 markup.highlight.noClasses=false 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 highlight shortcode. It 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: configure line numbers. Valid values are true, false, table, or inline. false will turn off line numbers if it’s configured to be on in site config. table will give copy-and-paste friendly code blocks.
hl_lines: lists a set of line numbers or line number ranges to be highlighted.
linenostart=199: starts the line number count from 199.
anchorlinenos: Configure anchors on line numbers. Valid values are true or false;
lineanchors: Configure a prefix for the anchors on line numbers. Will be suffixed with -, so linking to the line number 1 with the option lineanchors=prefix adds the anchor prefix-1 to the page.

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
ActionScript: actionscript, as
ActionScript 3: actionscript3, as, as3
Ada: ada, ada2005, ada95, adb, ads
AL: al, dal
Angular2: ng2
ANTLR: antlr
ApacheConf: aconf, apache, apacheconf, conf, htaccess
APL: apl
AppleScript: applescript
Arduino: arduino, ino
Awk: awk, gawk, mawk, nawk
Ballerina: bal, ballerina
Base Makefile: *, bsdmake, mak, make, makefile, mf, mk
Bash: bash, bash_*, bashrc, ebuild, eclass, env, exheres-0, exlib, ksh, sh, shell, zsh, zshrc
Batchfile: bat, batch, cmd, dosbatch, winbatch
BibTeX: bib, bibtex
BlitzBasic: b3d, bb, blitzbasic, bplus, decls
BNF: bnf
Brainfuck: b, bf, brainfuck
C: c, h, idc, x[bp]m
C#: c#, cs, csharp
C++: C, CPP, H, c++, cc, cp, cpp, cxx, h++, hh, hpp, hxx
Caddyfile: caddy, caddyfile
Caddyfile Directives: caddy-d, caddyfile-d, caddyfile-directives
Cap'n Proto: capnp
Cassandra CQL: cassandra, cql
Ceylon: ceylon
CFEngine3: cf, cf3, cfengine3
cfstatement: cfs
ChaiScript: chai, chaiscript
Cheetah: cheetah, spitfire, spt, tmpl
Clojure: clj, clojure
CMake: cmake, txt
COBOL: COB, CPY, cob, cobol, cpy
CoffeeScript: coffee, coffee-script, coffeescript
Common Lisp: cl, common-lisp, lisp
Coq: coq, v
Crystal: cr, crystal
CSS: css
Cython: cython, pxd, pxi, pyrex, pyx
D: d, di
Dart: dart
Diff: diff, patch, udiff
Django/Jinja: django, jinja
Docker: docker, dockerfile
DTD: dtd
Dylan: dyl, dylan, intr
EBNF: ebnf
Elixir: elixir, ex, exs
Elm: elm
EmacsLisp: el, elisp, emacs, emacs-lisp
Erlang: erl, erlang, es, escript, hrl
Factor: factor
Fish: fish, fishshell, load
Forth: forth, frt, fs, fth
Fortran: F03, F90, f03, f90, fortran
FortranFixed: F, f, fortranfixed
FSharp: fs, fsharp, fsi
GAS: S, asm, gas, s
GDScript: gd, gdscript
Genshi: genshi, kid, xml+genshi, xml+kid
Genshi HTML: html+genshi, html+kid
Genshi Text: genshitext
Gherkin: Cucumber, FEATURE, Gherkin, cucumber, feature, gherkin
GLSL: frag, geo, glsl, vert
Gnuplot: gnuplot, plot, plt
Go: go, golang
Go HTML Template: go-html-template
Go Text Template: go-text-template
GraphQL: gql, graphql, graphqls
Groff: 1p, 3pm, [1-9], groff, man, nroff
Groovy: gradle, groovy
Handlebars: handlebars, hbs
Haskell: haskell, hs
Haxe: haxe, hx, hxsl
HCL: hcl
Hexdump: hexdump
HLB: hlb
HTML: htm, html, xhtml, xslt
HTTP: http
Hy: hy, hylang
Idris: idr, idris
Igor: igor, igorpro, ipf
INI: cfg, dosini, editorconfig, gitconfig, inf, ini
Io: io
J: ijs, j
Java: java
JavaScript: javascript, js, jsm, mjs
JSON: json
Julia: jl, julia
Jungle: jungle
Kotlin: kotlin, kt
Lighttpd configuration file: lighttpd, lighty
LLVM: ll, llvm
Lua: lua, wlua
Mako: mako, mao
markdown: markdown, md, mkd
Mason: m, mason, mc, mhtml, mi
Mathematica: cdf, ma, mathematica, mma, nb, nbp
Matlab: m, matlab
mcfunction: mcfunction
Metal: metal
MiniZinc: MZN, dzn, fzn, minizinc, mzn
MLIR: mlir
Modula-2: def, m2, mod, modula2
MonkeyC: mc, monkeyc
MorrowindScript: morrowind, mwscript
Myghty: myghty, myt
MySQL: mysql, sql
NASM: ASM, asm, nasm
Newspeak: newspeak, ns2
Nginx configuration file: conf, nginx
Nim: nim, nimrod
Nix: nix, nixos
Objective-C: h, m, obj-c, objc, objective-c, objectivec
OCaml: ml, mli, mll, mly, ocaml
Octave: m, octave
OpenSCAD: openscad, scad
Org Mode: org, orgmode
PacmanConf: conf, pacmanconf
Perl: perl, pl, pm, t
PHP: inc, php, php3, php4, php5, php[345]
PHTML: inc, php, php[345], phtml
Pig: pig
PkgConfig: pc, pkgconfig
PL/pgSQL: plpgsql
plaintext: no-highlight, plain, text, txt
Pony: pony
PostgreSQL SQL dialect: postgres, postgresql
PostScript: eps, postscr, postscript, ps
POVRay: inc, pov
PowerQuery: powerquery, pq
PowerShell: posh, powershell, ps1, psd1, psm1
Prolog: ecl, pl, pro, prolog
PromQL: promql
Protocol Buffer: proto, protobuf
Puppet: pp, puppet
Python: bazel, bzl, jy, py, py3, pyi, python, python3, pyw, sage, sc, tac
Python 2: py2, python2
QBasic: BAS, bas, basic, qbasic
QML: qbs, qml
R: R, Renviron, Rhistory, Rprofile, S, r, s, splus
Racket: racket, rkt, rktd, rktl
Ragel: ragel
Raku: 6pl, 6pm, nqp, p6, p6l, p6m, perl6, pl, pl6, pm, pm6, raku, rakudoc, rakumod, rakutest, t
react: jsx, react
ReasonML: re, reason, reasonml, rei
reg: reg, registry
reStructuredText: rest, restructuredtext, rst
Rexx: arexx, rex, rexx, rx
Ruby: duby, gemspec, rake, rb, rbw, rbx, ruby
Rust: in, rs, rust
SAS: SAS, sas
Sass: sass
Scala: scala
Scheme: scheme, scm, ss
Scilab: sce, sci, scilab, tst
SCSS: scss
Smalltalk: smalltalk, squeak, st
Smarty: smarty, tpl
Snobol: snobol
Solidity: sol, solidity
SPARQL: rq, sparql
SQL: sql
SquidConf: conf, squid, squid.conf, squidconf
Standard ML: fun, sig, sml
Stylus: styl, stylus
Svelte: svelte
Swift: swift
SYSTEMD: automount, device, dnssd, link, mount, netdev, network, path, scope, service, slice, socket, swap, systemd, target, timer
systemverilog: sv, svh, systemverilog
TableGen: tablegen, td
TASM: ASM, asm, tasm
Tcl: rvt, tcl
Tcsh: csh, tcsh
Termcap: src, termcap
Terminfo: src, terminfo
Terraform: terraform, tf
TeX: aux, latex, tex, toc
Thrift: thrift
TOML: toml
TradingView: tradingview, tv
Transact-SQL: t-sql, tsql
Turing: tu, turing
Turtle: ttl, turtle
Twig: twig
TypeScript: ts, tsx, typescript
TypoScript: ts, typoscript
TypoScriptCssData: typoscriptcssdata
TypoScriptHtmlData: typoscripthtmldata
VB.net: bas, vb, vb.net, vbnet
verilog: v, verilog
VHDL: vhd, vhdl
VimL: exrc, gvimrc, vim, vimrc
vue: vue, vuejs
WDTE: wdte
XML: rss, svg, wsdl, wsf, xml, xsd, xsl, xslt
Xorg: conf, xorg.conf
YAML: yaml, yml
YANG: yang
Zig: zig