syntax-highlighting.md (4996B)
1 ---
2 title: Syntax Highlighting
3 description: Hugo comes with really fast syntax highlighting from Chroma.
4 date: 2017-02-01
5 publishdate: 2017-02-01
6 keywords: [highlighting,chroma,code blocks,syntax]
7 categories: [content management]
8 menu:
9 docs:
10 parent: "content-management"
11 weight: 300
12 weight: 20
13 sections_weight: 20
14 draft: false
15 aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
16 toc: true
17 ---
18
19 Hugo uses [Chroma](https://github.com/alecthomas/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.
20
21 ## Configure Syntax Highlighter
22
23 See [Configure Highlight](/getting-started/configuration-markup#highlight).
24
25 ## Generate Syntax Highlighter CSS
26
27 If you run with `markup.highlight.noClasses=false` in your site config, you need a style sheet.
28
29 You can generate one with Hugo:
30
31 ```bash
32 hugo gen chromastyles --style=monokai > syntax.css
33 ```
34
35 Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles.
36
37 ## Highlight Shortcode
38
39 Highlighting is carried out via the built-in [`highlight` shortcode](https://gohugo.io/content-management/shortcodes/#highlight). 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.
40
41 Options:
42
43 * `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. {{< new-in "0.60.0" >}} `table` will give copy-and-paste friendly code blocks.
44 * `hl_lines`: lists a set of line numbers or line number ranges to be highlighted.
45 * `linenostart=199`: starts the line number count from 199.
46 * `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`;
47 * `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.
48
49 ### Example: Highlight Shortcode
50
51 ```
52 {{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
53 // ... code
54 {{</* / highlight */>}}
55 ```
56
57 Gives this:
58
59 {{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}}
60 // GetTitleFunc returns a func that can be used to transform a string to
61 // title case.
62 //
63 // The supported styles are
64 //
65 // - "Go" (strings.Title)
66 // - "AP" (see https://www.apstylebook.com/)
67 // - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
68 //
69 // If an unknown or empty style is provided, AP style is what you get.
70 func GetTitleFunc(style string) func(s string) string {
71 switch strings.ToLower(style) {
72 case "go":
73 return strings.Title
74 case "chicago":
75 return transform.NewTitleConverter(transform.ChicagoStyle)
76 default:
77 return transform.NewTitleConverter(transform.APStyle)
78 }
79 }
80 {{< / highlight >}}
81
82 ## Highlight Template Func
83
84 See [Highlight](/functions/highlight/).
85
86 ## Highlighting in Code Fences
87
88 Highlighting in code fences is enabled by default.{{< new-in "0.60.0" >}}
89
90 ````
91 ```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
92 // ... code
93 ```
94 ````
95
96
97 Gives this:
98
99 ```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
100 // GetTitleFunc returns a func that can be used to transform a string to
101 // title case.
102 //
103 // The supported styles are
104 //
105 // - "Go" (strings.Title)
106 // - "AP" (see https://www.apstylebook.com/)
107 // - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
108 //
109 // If an unknown or empty style is provided, AP style is what you get.
110 func GetTitleFunc(style string) func(s string) string {
111 switch strings.ToLower(style) {
112 case "go":
113 return strings.Title
114 case "chicago":
115 return transform.NewTitleConverter(transform.ChicagoStyle)
116 default:
117 return transform.NewTitleConverter(transform.APStyle)
118 }
119 }
120 ```
121
122 {{< new-in "0.60.0" >}}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](https://github.com/yuin/goldmark-highlighting) for more information.
123
124 The options are the same as in the [highlighting shortcode](/content-management/syntax-highlighting/#highlight-shortcode),including `linenos=false`, but note the slightly different Markdown attribute syntax.
125
126 ## List of Chroma Highlighting Languages
127
128 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):
129
130 {{< chroma-lexers >}}
131
132 [Prism]: https://prismjs.com
133 [prismdownload]: https://prismjs.com/download.html
134 [Highlight.js]: https://highlightjs.org/
135 [Rainbow]: https://craig.is/making/rainbows
136 [Syntax Highlighter]: https://alexgorbatchev.com/SyntaxHighlighter/
137 [Google Prettify]: https://github.com/google/code-prettify
138 [Yandex]: https://yandex.ru/