Syntax highlighting

Hugo uses Chroma as its code highlighter; it is built in Go and is really, really fast.

Configure syntax highlighter

Generate syntax highlighter CSS

If you run with markup.highlight.noClasses=false in your site configuration, 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.

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 configuration. 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.
hl_inline Highlight inside a <code> (inline HTML element) tag. Valid values are true or false. The code tag will get a class with name code-inline.

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 Hugo/Go template code

For highlighting Hugo/Go template code on your page, add /* after the opening double curly braces and */ before closing curly braces.

{{</* myshortcode */>}}

Gives this:

{{< myshortcode >}}

Highlight template function

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

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
ABNF: abnf
ActionScript: as, actionscript
ActionScript 3: as3, actionscript3
Ada: ada, ada95, ada2005
AL: al
Angular2: ng2
ANTLR: antlr
ApacheConf: apacheconf, aconf, apache
APL: apl
AppleScript: applescript
ArangoDB AQL: aql
Arduino: arduino
ArmAsm: armasm
AutoHotkey: autohotkey, ahk
AutoIt: autoit
Awk: awk, gawk, mawk, nawk
Ballerina: ballerina
Bash: bash, sh, ksh, zsh, shell
BashSession: bash-session, console, shell-session
Batchfile: bat, batch, dosbatch, winbatch
BibTeX: bib, bibtex
Bicep: bicep
BlitzBasic: blitzbasic, b3d, bplus
BNF: bnf
BQN: bqn
Brainfuck: brainfuck, bf
C: c
C#: csharp, c#
C++: cpp, c++
Caddyfile: caddyfile, caddy
Caddyfile Directives: caddyfile-directives, caddyfile-d, caddy-d
Cap'n Proto: capnp
Cassandra CQL: cassandra, cql
Ceylon: ceylon
CFEngine3: cfengine3, cf3
cfstatement: cfs
ChaiScript: chai, chaiscript
Chapel: chapel, chpl
Cheetah: cheetah, spitfire
Clojure: clojure, clj
CMake: cmake
COBOL: cobol
CoffeeScript: coffee-script, coffeescript, coffee
Common Lisp: common-lisp, cl, lisp
Common Lisp: common-lisp, cl, lisp
Coq: coq
Crystal: cr, crystal
CSS: css
Cython: cython, pyx, pyrex
D: d
Dart: dart
Diff: diff, udiff
Django/Jinja: django, jinja
dns: zone, bind
Docker: docker, dockerfile
DTD: dtd
Dylan: dylan
EBNF: ebnf
Elixir: elixir, ex, exs
Elm: elm
EmacsLisp: emacs, elisp, emacs-lisp
EmacsLisp: emacs, elisp, emacs-lisp
Erlang: erlang
Factor: factor
Fennel: fennel, fnl
Fish: fish, fishshell
Forth: forth
Fortran: fortran, f90
FortranFixed: fortranfixed
FSharp: fsharp
GAS: gas, asm
GDScript: gdscript, gd
Genshi: genshi, kid, xml+genshi, xml+kid
Genshi HTML: html+genshi, html+kid
Genshi Text: genshitext
Gherkin: cucumber, Cucumber, gherkin, Gherkin
GLSL: glsl
Gnuplot: gnuplot
Go: go, golang
Go HTML Template: go-html-template
Go HTML Template: go-html-template
Go Text Template: go-text-template
GraphQL: graphql, graphqls, gql
Groff: groff, nroff, man
Groovy: groovy
Handlebars: handlebars, hbs
Haskell: haskell, hs
Haxe: hx, haxe, hxsl
HCL: hcl
Hexdump: hexdump
HLB: hlb
HLSL: hlsl
HolyC: holyc
HTML: html
HTTP: http
Hy: hylang
Idris: idris, idr
Igor: igor, igorpro
INI: ini, cfg, dosini
Io: io
ISCdhcpd: iscdhcpd
J: j
Java: java
JavaScript: js, javascript
JSON: json
Julia: julia, jl
Jungle: jungle
Kotlin: kotlin
Lighttpd configuration file: lighty, lighttpd
LLVM: llvm
Lua: lua
Makefile: make, makefile, mf, bsdmake
Mako: mako
markdown: md, mkd
Mason: mason
Mathematica: mathematica, mma, nb
Matlab: matlab
mcfunction: mcfunction
Meson: meson, meson.build
Metal: metal
MiniZinc: minizinc, MZN, mzn
MLIR: mlir
Modula-2: modula2, m2
MonkeyC: monkeyc
MorrowindScript: morrowind, mwscript
Myghty: myghty
MySQL: mysql, mariadb
NASM: nasm
Natural: natural
Newspeak: newspeak
Nginx configuration file: nginx
Nim: nim, nimrod
Nix: nixos, nix
Objective-C: objective-c, objectivec, obj-c, objc
OCaml: ocaml
Octave: octave
OnesEnterprise: ones, onesenterprise, 1S, 1S:Enterprise
OpenEdge ABL: openedge, abl, progress, openedgeabl
OpenSCAD: openscad
Org Mode: org, orgmode
PacmanConf: pacmanconf
Perl: perl, pl
PHP: php, php3, php4, php5
PHTML: phtml
Pig: pig
PkgConfig: pkgconfig
PL/pgSQL: plpgsql
plaintext: text, plain, no-highlight
Plutus Core: plutus-core, plc
Pony: pony
PostgreSQL SQL dialect: postgresql, postgres
PostScript: postscript, postscr
POVRay: pov
PowerQuery: powerquery, pq
PowerShell: powershell, posh, ps1, psm1, psd1, pwsh
Prolog: prolog
PromQL: promql
properties: java-properties
Protocol Buffer: protobuf, proto
PSL: psl
Puppet: puppet
Python: python, py, sage, python3, py3
Python 2: python2, py2
QBasic: qbasic, basic
QML: qml, qbs
R: splus, s, r
Racket: racket, rkt
Ragel: ragel
Raku: perl6, pl6, raku
react: jsx, react
ReasonML: reason, reasonml
reg: registry
reStructuredText: rst, rest, restructuredtext
Rexx: rexx, arexx
Ruby: rb, ruby, duby
Rust: rust, rs
SAS: sas
Sass: sass
Scala: scala
Scheme: scheme, scm
Scilab: scilab
SCSS: scss
Sed: sed, gsed, ssed
Sieve: sieve
Smali: smali
Smalltalk: smalltalk, squeak, st
Smarty: smarty
Snobol: snobol
Solidity: sol, solidity
SPARQL: sparql
SQL: sql
SquidConf: squidconf, squid.conf, squid
Standard ML: sml
stas
Stylus: stylus
Svelte: svelte
Swift: swift
SYSTEMD: systemd
systemverilog: systemverilog, sv
TableGen: tablegen
Tal: tal, uxntal
TASM: tasm
Tcl: tcl
Tcsh: tcsh, csh
Termcap: termcap
Terminfo: terminfo
Terraform: terraform, tf
TeX: tex, latex
Thrift: thrift
TOML: toml
TradingView: tradingview, tv
Transact-SQL: tsql, t-sql
Turing: turing
Turtle: turtle
Twig: twig
TypeScript: ts, tsx, typescript
TypoScript: typoscript
TypoScriptCssData: typoscriptcssdata
TypoScriptHtmlData: typoscripthtmldata
V: v, vlang
V shell: vsh, vshell
Vala: vala, vapi
VB.net: vb.net, vbnet
verilog: verilog, v
VHDL: vhdl
VHS: vhs, tape, cassette
VimL: vim
vue: vue, vuejs
WDTE
WebGPU Shading Language: wgsl
Whiley: whiley
XML: xml
Xorg: xorg.conf
YAML: yaml
YANG: yang
Z80 Assembly: z80
Zed: zed
Zig: zig

Syntax highlighting

Configure syntax highlighter

Generate syntax highlighter CSS

Highlight shortcode

Example: highlight shortcode

Highlight Hugo/Go template code

Highlight template function

Highlighting in code fences

List of Chroma highlighting languages

See Also

Last updated: July 13, 2023: Use sentence-style capitalization for headings (bc53ea5c)