highlight.md (3868B)
1 ---
2 title: highlight
3 linktitle: highlight
4 description: Renders code with a syntax highlighter.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2021-12-06
8 categories: [functions]
9 menu:
10 docs:
11 parent: "functions"
12 keywords: [highlighting,code blocks,syntax]
13 signature: ["transform.Highlight INPUT LANG [OPTIONS]","highlight INPUT LANG [OPTIONS]"]
14 relatedfuncs: []
15 deprecated: false
16 toc: true
17 ---
18 The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles.
19
20 ## Parameters
21
22 INPUT
23 : The code to highlight.
24
25 LANG
26 : The language of the code to highlight. Choose from one of the [supported languages]. Case-insensitive.
27
28 OPTIONS
29 : An optional, comma-separated list of zero or more [options]. Set default values in [site configuration].
30
31 ## Options
32
33 lineNos
34 : Boolean. Default is `false`.\
35 Display a number at the beginning of each line.
36
37 lineNumbersInTable
38 : Boolean. Default is `true`.\
39 Render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers. The right table cell contains the code, allowing a user to select and copy the code without line numbers. Irrelevant if `lineNos` is false.
40
41 anchorLineNos
42 : Boolean. Default is `false`.\
43 Render each line number as an HTML anchor element, and set the `id` attribute of the surrounding `<span>` to the line number. Irrelevant if `lineNos` is false.
44
45 lineAnchors
46 : String. Default is `""`.\
47 When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `<span>`. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is false.
48
49 lineNoStart
50 : Integer. Default is `1`.\
51 The number to display at the beginning of the first line. Irrelevant if `lineNos` is false.
52
53 hl_Lines
54 : String. Default is `""`.\
55 A space-separated list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
56
57 style
58 : String. Default is `monokai`.\
59 The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive.
60
61 noClasses
62 : Boolean. Default is `true`.\
63 Use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and [generate the file with the hugo client][hugo client].
64
65 tabWidth
66 : Integer. Default is `4`.\
67 Substitute this number of spaces for each tab character in your highlighted code.
68
69 guessSyntax
70 : Boolean. Default is `false`.\
71 If the `LANG` parameter is blank or an unrecognized language, auto-detect the language if possible, otherwise use a fallback language.
72
73 {{% note %}}
74 Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
75
76 `lineNos=inline`
77 : equivalent to `lineNos=true` and `lineNumbersInTable=false`
78
79 `lineNos=table`
80 : equivalent to `lineNos=true` and `lineNumbersInTable=true`
81 {{% /note %}}
82
83 ## Examples
84
85 ```go-html-template
86 {{ $input := `fmt.Println("Hello World!")` }}
87 {{ transform.Highlight $input "go" }}
88
89 {{ $input := `console.log('Hello World!');` }}
90 {{ $lang := "js" }}
91 {{ transform.Highlight $input $lang "lineNos=table, style=api" }}
92
93 {{ $input := `echo "Hello World!"` }}
94 {{ $lang := "bash" }}
95 {{ $options := slice "lineNos=table" "style=dracula" }}
96 {{ transform.Highlight $input $lang (delimit $options ",") }}
97 ```
98
99 [Chroma]: https://github.com/alecthomas/chroma
100 [hugo client]: {{< relref "commands/hugo_gen_chromastyles" >}}
101 [options]: {{< relref "#options" >}}
102 [site configuration]: {{< relref "getting-started/configuration-markup#highlight">}}
103 [style gallery]: https://xyproto.github.io/splash/docs/
104 [supported languages]: {{< relref "content-management/syntax-highlighting#list-of-chroma-highlighting-languages" >}}