transform.HighlightCodeBlock

The transform.HighlightCodeBlock function uses the alecthomas/chroma package to generate syntax-highlighted HTML from code received in context within a code block render hook. This function is only useful within a code block render hook.

Arguments

CONTEXT

The context passed into a code block render hook.

OPTIONS

(map) A map of key-value pairs. See the options below. The key names are case-insensitive.

Return value

transform.HighlightCodeBlock returns a HighlightResult object with two methods.

Wrapped

(template.HTML) Returns highlighted code wrapped in <div>, <pre>, and <code> elements. This is identical to the value returned by the transform.Highlight function.

Inner

(template.HTML) Returns highlighted code without any wrapping elements, allowing you to create your own wrapper.

Examples

{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}

To override the default options:

{{ $opts := merge .Options (dict "lineNos" true) }}
{{ $result := transform.HighlightCodeBlock . $opts }}
{{ $result.Wrapped }}

To fall back to plain text when the language is not supported by the highlighter:

{{ $opts := dict }}
{{ if not (transform.CanHighlight .Type) }}
  {{ $opts = dict "type" "text" }}
{{ end }}
{{ $result := transform.HighlightCodeBlock . $opts }}
{{ $result.Wrapped }}

Options

anchorLineNos

(bool) Whether to render each line number as an HTML anchor element, setting the id attribute of the surrounding span element to the line number. Irrelevant if lineNos is false. Default is false.

codeFences

(bool) Whether to highlight fenced code blocks. Default is true.

guessSyntax

(bool) Whether to automatically detect the language if the LANG argument is blank or set to a language for which there is no corresponding lexer. Falls back to a plain text lexer if unable to automatically detect the language. Default is false.

The syntax highlighter includes lexers for approximately 300 languages, but only 5 of these have implemented automatic language detection.

hl_Lines

(string) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to 2-4 7. This option is independent of the lineNoStart option.

hl_inline

(bool) Whether to render the highlighted code without a wrapping container. Default is false.

lineAnchors

(string) When rendering a line number as an HTML anchor element, prepend this value to the id attribute of the surrounding span element. This provides unique id attributes when a page contains two or more code blocks. Irrelevant if lineNos or anchorLineNos is false.

lineNoStart

(int) The number to display at the beginning of the first line. Irrelevant if lineNos is false. Default is 1.

lineNos

(any) Controls line number display. Default is false.

• true: Enable line numbers, controlled by lineNumbersInTable.
• false: Disable line numbers.
• inline: Enable inline line numbers (sets lineNumbersInTable to false).
• table: Enable table-based line numbers (sets lineNumbersInTable to true).

lineNumbersInTable

(bool) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if lineNos is false. Default is true.

noClasses

(bool) Whether to use inline CSS styles instead of an external CSS file. Default is true. To use an external CSS file, set this value to false and generate the CSS file from the command line:

hugo gen chromastyles --style=monokai > syntax.css

style

(string) The CSS styles to apply to the highlighted code. This value is case-insensitive. Default is monokai. See syntax highlighting styles.

tabWidth

(int) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if noClasses is false. Default is 4.

wrapperClass

New in v0.140.2

(string) The class or classes to use for the outermost element of the highlighted code. Default is highlight.

code

New in v0.162.0

(string) Overrides the code received from the code block context.

type

New in v0.162.0

(string) Overrides the language received from the code block context.