Highlight

The highlight shortcode renders your code with a syntax highlighter.

1print("Hello World!")

Usage

```py {lineNos="true" title="python" wrap="true"}
print("Hello World!")
```

{{< highlight lineNos="true" title="python" type="py" wrap="true" >}}
print("Hello World!")
{{< /highlight >}}

{{< highlight "py" "lineNos=true,title=python,wrap=true" >}}
print("Hello World!")
{{< /highlight >}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "print(\"Hello World!\")"
  "lineNos" "true"
  "title" "python"
  "type" "py"
  "wrap" "true"
)}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "print(\"Hello World!\")"
  "type" "py"
  "options" "lineNos=true,title=python,wrap=true"
)}}

This shortcode is fully compatible with Hugo’s highlight shortcode but offers some extensions.

It is called interchangeably in the same way as Hugo’s own shortcode by providing positional parameters or simply by using Markdown codefences.

You are free to also call this shortcode from your own partials. In this case it resembles Hugo’s highlight function syntax if you call it using compatibility syntax.

Markdown codefence syntax is widely available in other Markdown parsers like GitHub and therefore is the recommended syntax for generating portable Markdown.

The tab shortcode is also capable of displaying code but with limited options.

Parameters

Name	Position	Default	Notes
type	1	<empty>	The language of the code to highlight. Choose from one of the supported languages. Case-insensitive.
title		<empty>	Extension. Arbitrary title for code. This displays the code like a single tab if `hl_inline=false` (which is Hugo’s default).
wrap		see notes	Extension. When `true` the content may wrap on long lines otherwise it will be scrollable. The default value can be set in your `hugo.toml` and overwritten via front matter. See below.
options	2	<empty>	An optional, comma-separated list of zero or more Hugo supported options as well as extension parameter from this table.
<option>		<empty>	Any of Hugo’s supported options.
<content>		<empty>	Your code to highlight.

Settings

Setting Default Values for Hugo’s Options

Default values for Hugo’s supported options can be set via goldmark settings.

If used together with wrapping of long lines, use this recommended settings. Otherwise, line numbers will shift if code wraps.

hugo.

[markup]
  [markup.highlight]
    lineNumbersInTable = false

markup:
  highlight:
    lineNumbersInTable: false

{
   "markup": {
      "highlight": {
         "lineNumbersInTable": false
      }
   }
}

Setting Wrap of Long Lines

Option Front Matter By default, code will be wrapped if the line is not long enough.

You can disable wrapping by setting highlightWrap=false or by setting the wrap parameter individually for each code block.

[params]
  highlightWrap = false

params:
  highlightWrap: false

{
   "params": {
      "highlightWrap": false
   }
}

Copy to Clipboard for Inline Code

Option By default inline code has a button to copy the code to the clipboard.

If you want to disable this feature, set disableInlineCopyToClipBoard=true.

hugo.

[params]
  disableInlineCopyToClipBoard = true

params:
  disableInlineCopyToClipBoard: true

{
   "params": {
      "disableInlineCopyToClipBoard": true
   }
}

Copy to Clipboard for Block Code

Option By default block code has a button to copy the code to the clipboard that is only visible on hover.

Set disableHoverBlockCopyToClipBoard=true to disable the hover effect and always show the button.

hugo.

[params]
  disableHoverBlockCopyToClipBoard = true

params:
  disableHoverBlockCopyToClipBoard: true

{
   "params": {
      "disableHoverBlockCopyToClipBoard": true
   }
}

Setting a Specific Color Scheme

You can configure the color style used for code blocks in your color variants stylesheet file using the --CODE-theme variable. This requires further configuration as described in the above link.

Examples

Line Numbers with Starting Offset

As mentioned above, line numbers in a table layout will shift if code is wrapping, so better use inline. To make things easier for you, set lineNumbersInTable = false in your hugo.toml and add lineNos = true when calling the shortcode instead of the specific values table or inline.

```py {lineNoStart="666" lineNos="true"}
# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
print("Hello")
print(" ")
print("World")
print("!")
```

{{< highlight lineNoStart="666" lineNos="true" type="py" >}}
# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
print("Hello")
print(" ")
print("World")
print("!")
{{< /highlight >}}

{{< highlight "py" "lineNoStart=666,lineNos=true" >}}
# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
print("Hello")
print(" ")
print("World")
print("!")
{{< /highlight >}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits\nprint(\"Hello\")\nprint(\" \")\nprint(\"World\")\nprint(\"!\")"
  "lineNoStart" "666"
  "lineNos" "true"
  "type" "py"
)}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits\nprint(\"Hello\")\nprint(\" \")\nprint(\"World\")\nprint(\"!\")"
  "type" "py"
  "options" "lineNoStart=666,lineNos=true"
)}}

666# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
667print("Hello")
668print(" ")
669print("World")
670print("!")

With Title

```py {title="python"}
# a bit shorter
print("Hello World!")
```

{{< highlight title="python" type="py" >}}
# a bit shorter
print("Hello World!")
{{< /highlight >}}

{{< highlight "py" "title=python" >}}
# a bit shorter
print("Hello World!")
{{< /highlight >}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "# a bit shorter\nprint(\"Hello World!\")"
  "title" "python"
  "type" "py"
)}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "# a bit shorter\nprint(\"Hello World!\")"
  "type" "py"
  "options" "title=python"
)}}

# a bit shorter
print("Hello World!")

With Wrap

```py {hl_lines="2" wrap="true"}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
```

{{< highlight hl_lines="2" type="py" wrap="true" >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
{{< /highlight >}}

{{< highlight "py" "hl_lines=2,wrap=true" >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
{{< /highlight >}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "# Quicksort Python One-liner\nlambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])\n# Some more stuff"
  "hl_lines" "2"
  "type" "py"
  "wrap" "true"
)}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "# Quicksort Python One-liner\nlambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])\n# Some more stuff"
  "type" "py"
  "options" "hl_lines=2,wrap=true"
)}}

# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff

Without Wrap

```py {hl_lines="2" wrap="false"}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
```

{{< highlight hl_lines="2" type="py" wrap="false" >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
{{< /highlight >}}

{{< highlight "py" "hl_lines=2,wrap=false" >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
{{< /highlight >}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "# Quicksort Python One-liner\nlambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])\n# Some more stuff"
  "hl_lines" "2"
  "type" "py"
  "wrap" "false"
)}}

{{ partial "shortcodes/highlight.html" (dict
  "page" .
  "content" "# Quicksort Python One-liner\nlambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])\n# Some more stuff"
  "type" "py"
  "options" "hl_lines=2,wrap=false"
)}}

# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff