1 files changed, 63 insertions, 120 deletions
diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md
index 6b277365f..1220a06c8 100644
--- a/content/en/content-management/syntax-highlighting.md
+++ b/content/en/content-management/syntax-highlighting.md
@@ -3,7 +3,7 @@ title: Syntax Highlighting
 description: Hugo comes with really fast syntax highlighting from Chroma.
 date: 2017-02-01
 publishdate: 2017-02-01
-keywords: [highlighting,pygments,chroma,code blocks,syntax]
+keywords: [highlighting,chroma,code blocks,syntax]
 categories: [content management]
 menu:
   docs:
@@ -16,17 +16,39 @@ aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
 toc: true
 ---
 
-From Hugo 0.28, the default syntax highlighter 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.
 
-If you want to continue to use Pygments (see below), set `pygmentsUseClassic=true` in your site config.
+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.
 
-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)).
+## Configure Syntax Highlighter
+
+See [Configure Highlight](/getting-started/configuration-markup#highlight).
+
+
+## Generate Syntax Highlighter CSS
+
+If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet.
+
+You can generate one with Hugo:
 
-* `linenos=inline` or `linenos=table` (`table` will give copy-and-paste friendly code blocks) turns on line numbers.
-* `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.
+```bash
+hugo gen chromastyles --style=monokai > syntax.css
+```
+
+Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles.
+
+
+## Highlight Shortcode
+
+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.
+
+Options:
+
+* `linenos`: Valid values are `true`, `false`, `table`, `inline`. `table` will give copy-and-paste friendly code blocks) turns on line numbers.
+* Setting `linenos` to `false` will turn off linenumbers if it's configured to be on in site config.{{< new-in "0.60.0" >}}
+* `hl_lines` lists a set of line numbers or line number ranges to be highlighted.
 * `linenostart=199` starts the line number count from 199.
 
-With that, this:
+### Example: Highlight Shortcode
 
 ```
 {{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
@@ -52,143 +74,64 @@ func GetTitleFunc(style string) func(s string) string {
   case "go":
     return strings.Title
   case "chicago":
-    tc := transform.NewTitleConverter(transform.ChicagoStyle)
-    return tc.Title
+    return transform.NewTitleConverter(transform.ChicagoStyle)
   default:
-    tc := transform.NewTitleConverter(transform.APStyle)
-    return tc.Title
+    return transform.NewTitleConverter(transform.APStyle)
   }
 }
 {{< / highlight >}}
 
 
-## Configure Syntax Highlighter
-To make the transition from Pygments to Chroma seamless, they share a common set of configuration options:
-
-pygmentsOptions
-:  A comma separated list of options. See below for a full list.
-
-pygmentsCodeFences
-: Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example).
-
-pygmentsStyle
-: The style of code highlighting. Note that this option is not
-  relevant when `pygmentsUseClasses` is set.
-
-  Syntax highlighting galleries:
-  **Chroma** ([short snippets](https://xyproto.github.io/splash/docs/all.html),
-  [long snippets](https://xyproto.github.io/splash/docs/longer/all.html)),
-  [Pygments](https://help.farbox.com/pygments.html)
-
-pygmentsUseClasses
-: Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css).
-
-pygmentsCodeFencesGuessSyntax
-: Set to `true` to try to do syntax highlighting on code fenced blocks in markdown without a language tag.
-
-pygmentsUseClassic
-: Set to true to use Pygments instead of the much faster Chroma.
-
-### Options
-
-`pygmentsOptions` can be set either in site config or overridden per code block in the Highlight shortcode or template func.
-
-noclasses
-: Use inline style.
-
-linenos
-: For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control.
-
-linenostart
-: Start the line numbers from this value (default is 1).
-
-
-hl_lines
-: Highlight a space separated list of line numbers. For Chroma, you can provide a list of ranges, i.e. "3-8 10-20".
-
-
-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.
-
-
-## Generate Syntax Highlighter CSS
-
-If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet.
-
-You can generate one with Hugo:
-
-```bash
-hugo gen chromastyles --style=monokai > syntax.css
-```
-
-Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles.
-
-
-## Highlight Shortcode
-
-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.
-
-### Example `highlight` Shortcode
-
-{{< code file="example-highlight-shortcode-input.md" >}}
-{{</* highlight html */>}}
-<section id="main">
-  <div>
-    <h1 id="title">{{ .Title }}</h1>
-    {{ range .Pages }}
-      {{ .Render "summary"}}
-    {{ end }}
-  </div>
-</section>
-{{</* /highlight */>}}
-{{< /code >}}
-
-
 
 ## Highlight Template Func
 
 See [Highlight](/functions/highlight/).
 
-## Highlight in Code Fences
+## Highlighting in Code Fences
 
-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/);
+Highlighting in code fences is enabled by default.{{< new-in "0.60.0" >}}
 
 ````
-```go-html-template
-<section id="main">
-  <div>
-    <h1 id="title">{{ .Title }}</h1>
-    {{ range .Pages }}
-      {{ .Render "summary"}}
-    {{ end }}
-  </div>
-</section>
+```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
+// ... code
 ```
 ````
 
-## List of Chroma Highlighting Languages
 
-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):
-
-{{< chroma-lexers >}}
-
-## Highlight with Pygments Classic
-
-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.
+Gives this:
 
-{{% note "Disclaimers on Pygments" %}}
-* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
-* The caching can be turned off by setting the `--ignoreCache` flag to `true`.
-* The languages available for highlighting depend on your Pygments installation.
-{{% /note %}}
+```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
+// GetTitleFunc returns a func that can be used to transform a string to
+// title case.
+//
+// The supported styles are
+//
+// - "Go" (strings.Title)
+// - "AP" (see https://www.apstylebook.com/)
+// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html)
+//
+// If an unknown or empty style is provided, AP style is what you get.
+func GetTitleFunc(style string) func(s string) string {
+  switch strings.ToLower(style) {
+  case "go":
+    return strings.Title
+  case "chicago":
+    return transform.NewTitleConverter(transform.ChicagoStyle)
+  default:
+    return transform.NewTitleConverter(transform.APStyle)
+  }
+}
+```
 
-If you have never worked with Pygments before, here is a brief primer:
+{{< 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.
 
-+ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
-+ 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.
+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.
 
-On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`.
+## List of Chroma Highlighting Languages
 
+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):
 
+{{< chroma-lexers >}}
 
 [Prism]: https://prismjs.com
 [prismdownload]: https://prismjs.com/download.html