gohugoio/hugo · error

invalid Highlight option: %s

Error message

invalid Highlight option: %s

What it means

`parseHighlightOptions` parses a comma-separated `key=value` options string used by Hugo's highlight shortcode/function and the legacy `pygmentsOptions` site setting. Each comma-separated segment must split into exactly one key and one value on "="; a segment with no "=" or with multiple "=" signs aborts parsing with this error naming the offending key.

Source

Thrown at markup/highlight/config.go:253

		}
	}

	return nil
}

func parseHighlightOptions(in string) (map[string]any, error) {
	in = strings.Trim(in, " ")
	opts := make(map[string]any)

	if in == "" {
		return opts, nil
	}

	for v := range strings.SplitSeq(in, ",") {
		keyVal := strings.Split(v, "=")
		key := strings.Trim(keyVal[0], " ")
		if len(keyVal) != 2 {
			return opts, fmt.Errorf("invalid Highlight option: %s", key)
		}
		opts[key] = keyVal[1]

	}

	normalizeHighlightOptions(opts)

	return opts, nil
}

func normalizeHighlightOptions(m map[string]any) {
	if m == nil {
		return
	}

	// lowercase all keys
	for k, v := range m {
		delete(m, k)

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Format every option as key=value, comma-separated with no trailing comma, e.g. "linenos=table,hl_lines=2 4,linenostart=10".
2. Remove or fix the segment named in the error message (it prints the bad key).
3. If a value needs "=", it isn't supported here — restructure the option or set it in site config under markup.highlight instead.

Example fix

{{/* before */}}
{{< highlight go "linenos,hl_lines=2" >}}
{{/* after */}}
{{< highlight go "linenos=table,hl_lines=2" >}}

validOpts := map[string]bool{"style": true, "lineNos": true, "lineNumbersInTable": true, "hl_Lines": true, "linenostart": true, "anchorLineNos": true, "lineAnchors": true, "hl_inline": true, "noClasses": true, "tabWidth": true, "guessSyntax": true, "wrapperClass": true}
for k := range userOpts {
    if !validOpts[k] {
        return fmt.Errorf("unknown highlight option %q", k)
    }
}

When it happens

Trigger: A `{{< highlight go "linenos=table,hl_lines" >}}` shortcode or `transform.Highlight`/`highlight` template call where an option segment lacks `=value`; a value itself containing "=" (splits into 3 parts); a trailing comma producing an empty segment; or a malformed `pygmentsOptions` string in site config.

Common situations: Typos in shortcode option strings (missing "=", using ":" instead of "="), passing space-separated instead of comma-separated options, quoting issues in templates that swallow the value, and old Pygments-era configs migrated forward with stray commas.

Related errors

• failed to unmarshal config for path %q: %w
• failed to load config: %w
• invalid style: %s
• invalid mode: %s
• style %q does not have a %q mode

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/308af3223ec3d8bc.json. Report an issue: GitHub ↗.