hugo

Fork of github.com/gohugoio/hugo with reverse pagination support

git clone git://git.shimmy1996.com/hugo.git

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/