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/