github.com/shohhei1126/hugo@v0.42.2-0.20180623210752-3d5928889ad7/docs/content/en/content-management/syntax-highlighting.md (about)

     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,pygments,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  From Hugo 0.28, the default syntax hightlighter in Hugo is [Chroma](https://github.com/alecthomas/chroma); it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments.
    20  
    21  If you want to continue to use Pygments (see below), set `pygmentsUseClassic=true` in your site config.
    22  
    23  The example below shows a simple code snippet from the Hugo source highlighted with the `highlight` shortcode. Note that the gohugo.io site is generated with `pygmentsUseClasses=true` (see [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css)).
    24  
    25  * `linenos=inline` or `linenos=table` (`table` will give copy-and-paste friendly code blocks) turns on line numbers.
    26  * `hl_lines` lists a set of line numbers or line number ranges to be highlighted. Note that the hyphen range syntax is only supported for Chroma.
    27  * `linenostart=199` starts the line number count from 199.
    28  
    29  With that, this:
    30  
    31  ```
    32  {{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
    33  // ... code
    34  {{</* / highlight */>}}
    35  ```
    36  
    37  Gives this:
    38  
    39  {{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}}
    40  // GetTitleFunc returns a func that can be used to transform a string to
    41  // title case.
    42  //
    43  // The supported styles are
    44  //
    45  // - "Go" (strings.Title)
    46  // - "AP" (see https://www.apstylebook.com/)
    47  // - "Chicago" (see http://www.chicagomanualofstyle.org/home.html)
    48  //
    49  // If an unknown or empty style is provided, AP style is what you get.
    50  func GetTitleFunc(style string) func(s string) string {
    51    switch strings.ToLower(style) {
    52    case "go":
    53      return strings.Title
    54    case "chicago":
    55      tc := transform.NewTitleConverter(transform.ChicagoStyle)
    56      return tc.Title
    57    default:
    58      tc := transform.NewTitleConverter(transform.APStyle)
    59      return tc.Title
    60    }
    61  }
    62  {{< / highlight >}}
    63  
    64  
    65  ## Configure Syntax Highlighter
    66  To make the transition from Pygments to Chroma seamless, they share a common set of configuration options:
    67  
    68  pygmentsOptions
    69  :  A comma separated list of options. See below for a full list.
    70  
    71  pygmentsCodefences
    72  : Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example).
    73  
    74  pygmentsStyle
    75  : The style of code highlighting. See https://help.farbox.com/pygments.html for a gallery. Note that this option is not relevant when `pygmentsUseClasses` is set.
    76  
    77  pygmentsUseClasses
    78  : Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css).
    79  
    80  pygmentsCodefencesGuessSyntax
    81  : Set to `true` to try to do syntax highlighting on code fenced blocks in markdown without a language tag.
    82  
    83  pygmentsUseClassic
    84  : Set to true to use Pygments instead of the much faster Chroma.
    85  
    86  ### Options
    87  
    88  `pygmentsOptions` can be set either in site config or overridden per code block in the Highlight shortcode or template func.
    89  
    90  noclasses
    91  : Use inline style.
    92  
    93  linenos
    94  : For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control.
    95  
    96  linenostart
    97  : Start the line numbers from this value (default is 1).
    98  
    99  
   100  hl_lines
   101  : Highlight a space separated list of line numbers. For Chroma, you can provide a list of ranges, i.e. "3-8 10-20".
   102  
   103  
   104  The full set of supported options for Pygments is: `encoding`, `outencoding`, `nowrap`, `full`, `title`, `style`, `noclasses`, `classprefix`, `cssclass`, `cssstyles`, `prestyles`, `linenos`, `hl_lines`, `linenostart`, `linenostep`, `linenospecial`, `nobackground`, `lineseparator`, `lineanchors`, `linespans`, `anchorlinenos`, `startinline`. See the [Pygments HTML Formatter Documentation](http://pygments.org/docs/formatters/#HtmlFormatter) for details.
   105  
   106  
   107  ## Generate Syntax Highlighter CSS
   108  
   109  If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet.
   110  
   111  You can generate one with Hugo:
   112  
   113  ```bash
   114  hugo gen chromastyles --style=monokai > syntax.css
   115  ```
   116  
   117  Run `hugo gen chromastyles -h` for more options. See https://help.farbox.com/pygments.html for a gallery of available styles.
   118  
   119  
   120  ## Highlight Shortcode
   121  
   122  Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` 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.
   123  
   124  ### Example `highlight` Shortcode
   125  
   126  {{< code file="example-highlight-shortcode-input.md" >}}
   127  {{</* highlight html */>}}
   128  <section id="main">
   129    <div>
   130      <h1 id="title">{{ .Title }}</h1>
   131      {{ range .Data.Pages }}
   132        {{ .Render "summary"}}
   133      {{ end }}
   134    </div>
   135  </section>
   136  {{</* /highlight */>}}
   137  {{< /code >}}
   138  
   139  
   140  
   141  ## Highlight Template Func
   142  
   143  See [Highlight](/functions/highlight/).
   144  
   145  ## Highlight in Code Fences
   146  
   147  It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `pygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/);
   148  
   149  ````
   150  ```go-html-template
   151  <section id="main">
   152    <div>
   153      <h1 id="title">{{ .Title }}</h1>
   154      {{ range .Data.Pages }}
   155        {{ .Render "summary"}}
   156      {{ end }}
   157    </div>
   158  </section>
   159  ```
   160  ````
   161  
   162  ## List of Chroma Highlighting Languages
   163  
   164  The full list of Chroma lexers and their aliases (which is the identifier used in the `hightlight` template func or when doing highlighting in code fences):
   165  
   166  {{< chroma-lexers >}}
   167  
   168  ## Highlight with Pygments Classic
   169  
   170  If you for some reason don't want to use the built-in Chroma highlighter, you can set `pygmentsUseClassic=true` in your config and add Pygments to your path.
   171  
   172  {{% note "Disclaimers on Pygments" %}}
   173  * Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
   174  * The caching can be turned off by setting the `--ignoreCache` flag to `true`.
   175  * The languages available for highlighting depend on your Pygments installation.
   176  {{% /note %}}
   177  
   178  If you have never worked with Pygments before, here is a brief primer:
   179  
   180  + Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
   181  + Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it.
   182  
   183  On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`.
   184  
   185  
   186  
   187  [Prism]: http://prismjs.com
   188  [prismdownload]: http://prismjs.com/download.html
   189  [Highlight.js]: http://highlightjs.org/
   190  [Rainbow]: http://craig.is/making/rainbows
   191  [Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/
   192  [Google Prettify]: https://github.com/google/code-prettify
   193  [Yandex]: http://yandex.ru/