1 files changed, 63 insertions, 99 deletions
diff --git a/docs/content/en/content-management/syntax-highlighting.md b/docs/content/en/content-management/syntax-highlighting.md
index b3e991a96..7e87efa49 100644
--- a/docs/content/en/content-management/syntax-highlighting.md
+++ b/docs/content/en/content-management/syntax-highlighting.md
@@ -1,138 +1,102 @@
 ---
 title: Syntax highlighting
-description: Hugo comes with really fast syntax highlighting from Chroma.
-categories: [content management]
-keywords: [highlighting,chroma,code blocks,syntax]
-menu:
-  docs:
-    parent: content-management
-    weight: 250
-weight: 250
-toc: true
+description: Add syntax highlighting to code examples.
+categories: []
+keywords: [highlight]
 aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
 ---
 
-Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast.
+Hugo provides several methods to add syntax highlighting to code examples:
 
-## Configure syntax highlighter
+- Use the [`transform.Highlight`] function within your templates
+- Use the [`highlight`] shortcode with any [content format](g)
+- Use fenced code blocks with the Markdown content format
 
-See [Configure Highlight](/getting-started/configuration-markup#highlight).
+[`transform.Highlight`]: /functions/transform/highlight/
+[`highlight`]: /shortcodes/highlight/
 
-## Generate syntax highlighter CSS
+## Fenced code blocks
 
-If you run with `markup.highlight.noClasses=false` in your site configuration, you need a style sheet. The style sheet will override the style specified in [`markup.highlight.style`](/functions/transform/highlight/#options).
+In its default configuration, Hugo highlights code examples within fenced code blocks, following this form:
 
-You can generate one with Hugo:
-
-```sh
-hugo gen chromastyles --style=monokai > syntax.css
+````text {file="content/example.md"}
+```LANG [OPTIONS]
+CODE
 ```
+````
 
-Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles.
+CODE
+: The code to highlight.
 
-## Highlight shortcode
+LANG
+: The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
 
-Highlighting is carried out via the built-in [`highlight` shortcode](/shortcodes/highlight/). It takes exactly one required argument for the programming language to be highlighted and requires a closing tag.
+OPTIONS
+: One or more space-separated or comma-separated key-value pairs wrapped in braces. Set default values for each option in your [site configuration]. The key names are case-insensitive.
 
-Options:
+[supported languages]: #languages
+[site configuration]: /configuration/markup/#highlight
 
-* `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 configuration. `table` will give copy-and-paste friendly code blocks.
-* `hl_lines`: lists a set of line numbers or line number ranges to be highlighted.
-* `linenostart=199`: starts the line number count from 199.
-* `anchorlinenos`: Configure anchors on line numbers. Valid values are `true` or `false`;
-* `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.  
-* `hl_inline`  Highlight inside a `<code>` (inline HTML element) tag. Valid values are `true` or `false`. The `code` tag will get a class with name `code-inline`.
+For example, with this Markdown:
 
-### Example: highlight shortcode
+````text {file="content/example.md"}
+```go {linenos=inline hl_lines=[3,"6-8"] style=emacs}
+package main
 
-```go-html-template
-{{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
-// ... code
-{{</* / highlight */>}}
-```
+import "fmt"
 
-Gives this:
-
-{{< highlight 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)
-  }
+func main() {
+    for i := 0; i < 3; i++ {
+        fmt.Println("Value of i:", i)
+    }
 }
-{{< / highlight >}}
-
-## Highlight Hugo/Go template code
+```
+````
 
-For highlighting Hugo/Go template code on your page, add `/*` after the opening double curly braces and `*/` before closing curly braces.
+Hugo renders this:
 
-``` go
-{{</*/* myshortcode */*/>}}
-```
+```go {linenos=inline, hl_lines=[3, "6-8"], style=emacs}
+package main
 
-Gives this:
+import "fmt"
 
-``` go
-{{</* myshortcode */>}}
+func main() {
+    for i := 0; i < 3; i++ {
+        fmt.Println("Value of i:", i)
+    }
+}
 ```
 
-## Highlight template function
+## Options
+
+{{% include "_common/syntax-highlighting-options.md" %}}
 
-See [Highlight](/functions/transform/highlight/).
+## Escaping
 
-## Highlighting in code fences
+When documenting shortcode usage, escape the tag delimiters:
 
-Highlighting in code fences is enabled by default.
+````text {file="content/example.md"}
+```text {linenos=inline}
+{{</*/* shortcode-1 */*/>}}
 
-````txt
-```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
-// ... code
+{{%/*/* shortcode-2 */*/%}}
 ```
 ````
 
-Gives this:
-
-```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)
-  }
-}
+Hugo renders this to:
+
+```text {linenos=inline}
+{{</* shortcode-1 */>}}
+
+{{%/* shortcode-2 */%}}
 ```
 
-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.
+## Languages
 
-## List of Chroma highlighting languages
+These are the supported languages. Use one of the identifiers, not the language name, when specifying a language for:
 
-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):
+- The [`transform.Highlight`] function
+- The [`highlight`] shortcode
+- Fenced code blocks
 
 {{< chroma-lexers >}}