markup/highlight: Allow overriding type and code via options

Treat type and code as highlighting options in both transform.Highlight
and transform.HighlightCodeBlock. The type option overrides the language
and code overrides the code, so the two functions now share the same
options handling.

transform.Highlight's LANG argument is now optional:

	transform.Highlight CODE [LANG] [OPTIONS]

Fixes #11872
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bep

docs/content/en/functions/transform/Highlight.md

@@ -7,24 +7,22 @@ params:
   functions_and_methods:
     aliases: [highlight]
     returnType: template.HTML
-    signatures: ['transform.Highlight CODE LANG [OPTIONS]']
+    signatures: ['transform.Highlight CODE [LANG] [OPTIONS]']
 aliases: [/functions/highlight]
 ---
 
 The `transform.Highlight` function uses the [`alecthomas/chroma`][] package to generate syntax-highlighted HTML from the provided code, [language][], and [options][].
 
 ## Arguments
 
-The `transform.Highlight` function takes three arguments.
-
 CODE
 : (`string`) The code to highlight.
 
 LANG
-: (`string`) The [language][] of the code to highlight. This value is case-insensitive.
+: (`string`) The [language][] of the code to highlight. This value is case-insensitive. Optional; you can also set the language with the `type` key in OPTIONS. {{< new-in "0.162.0" />}}
 
 OPTIONS
-: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. You can set default values for each option in your [project configuration][]. The key names are case-insensitive.
+: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. You can set default values for each option in your [project configuration][]. The key names are case-insensitive. In addition to the [highlighting options](#options-1), the `type` and `code` keys override the `LANG` and `CODE` arguments respectively. {{< new-in "0.162.0" />}}
 
 ## Examples
 
@@ -40,6 +38,10 @@ OPTIONS
 {{ $lang := "bash" }}
 {{ $opts := dict "lineNos" "table" "style" "dracula" }}
 {{ transform.Highlight $input $lang $opts }}
+
+{{ $input := `print("Hello World!")` }}
+{{ $opts := dict "type" "python" "style" "dracula" }}
+{{ transform.Highlight $input $opts }}
 ```
 
 ## Options

docs/content/en/functions/transform/HighlightCodeBlock.md

@@ -33,4 +33,15 @@ To override the default [highlighting options]:
 {{ $result.Wrapped }}
 ```
 
+The `type` and `code` keys are special: they override the language and the code received from the code block respectively. {{< new-in "0.162.0" />}} For example, to fall back to plain text when the language is not supported by the highlighter:
+
+```go-html-template
+{{ $opts := dict }}
+{{ if not (transform.CanHighlight .Type) }}
+  {{ $opts = dict "type" "text" }}
+{{ end }}
+{{ $result := transform.HighlightCodeBlock . $opts }}
+{{ $result.Wrapped }}
+```
+
 [highlighting options]: /functions/transform/highlight/#options

markup/highlight/config.go

@@ -148,33 +148,54 @@ func (cfg Config) toHTMLOptions() ([]html.Option, error) {
 	return options, nil
 }
 
-func applyOptions(opts any, cfg *Config) error {
+func applyOptionsFromString(opts string, cfg *Config) error {
+	optsm, err := parseHighlightOptions(opts)
+	if err != nil {
+		return err
+	}
+	return mapstructure.WeakDecode(optsm, cfg)
+}
+
+func applyOptionsFromMap(optsm map[string]any, cfg *Config) error {
+	normalizeHighlightOptions(optsm)
+	return mapstructure.WeakDecode(optsm, cfg)
+}
+
+// applyOptions applies opts (a string or a map) to cfg. The type and code
+// options, if set, are not part of Config and instead override lang and code
+// respectively. Shared by Highlight and HighlightCodeBlock. See issue 11872.
+func applyOptions(opts any, cfg *Config, lang, code *string) error {
 	if opts == nil {
 		return nil
 	}
+
+	var optsm map[string]any
 	switch vv := opts.(type) {
 	case map[string]any:
-		return applyOptionsFromMap(vv, cfg)
+		optsm = make(map[string]any, len(vv))
+		for k, v := range vv {
+			optsm[strings.ToLower(k)] = v
+		}
 	default:
 		s, err := cast.ToStringE(opts)
 		if err != nil {
 			return err
 		}
-		return applyOptionsFromString(s, cfg)
+		if optsm, err = parseHighlightOptions(s); err != nil {
+			return err
+		}
 	}
-}
 
-func applyOptionsFromString(opts string, cfg *Config) error {
-	optsm, err := parseHighlightOptions(opts)
-	if err != nil {
-		return err
+	if v, found := optsm["type"]; found {
+		*lang = cast.ToString(v)
+		delete(optsm, "type")
+	}
+	if v, found := optsm["code"]; found {
+		*code = cast.ToString(v)
+		delete(optsm, "code")
 	}
-	return mapstructure.WeakDecode(optsm, cfg)
-}
 
-func applyOptionsFromMap(optsm map[string]any, cfg *Config) error {
-	normalizeHighlightOptions(optsm)
-	return mapstructure.WeakDecode(optsm, cfg)
+	return applyOptionsFromMap(optsm, cfg)
 }
 
 func applyOptionsFromCodeBlockContext(ctx hooks.CodeblockContext, cfg *Config) error {

markup/highlight/highlight.go

@@ -71,7 +71,7 @@ type chromaHighlighter struct {
 
 func (h chromaHighlighter) Highlight(code, lang string, opts any) (string, error) {
 	cfg := h.cfg
-	if err := applyOptions(opts, &cfg); err != nil {
+	if err := applyOptions(opts, &cfg, &lang, &code); err != nil {
 		return "", err
 	}
 	var b strings.Builder
@@ -90,22 +90,22 @@ func (h chromaHighlighter) HighlightCodeBlock(ctx hooks.CodeblockContext, opts a
 
 	attributes := ctx.(hooks.AttributesOptionsSliceProvider).AttributesSlice()
 
-	options := ctx.Options()
-
-	if err := applyOptionsFromMap(options, &cfg); err != nil {
+	if err := applyOptionsFromMap(ctx.Options(), &cfg); err != nil {
 		return HighlightResult{}, err
 	}
 
-	// Apply these last so the user can override them.
-	if err := applyOptions(opts, &cfg); err != nil {
+	lang, code := ctx.Type(), ctx.Inner()
+
+	// Apply these last so the user can override them, including the type and code.
+	if err := applyOptions(opts, &cfg, &lang, &code); err != nil {
 		return HighlightResult{}, err
 	}
 
 	if err := applyOptionsFromCodeBlockContext(ctx, &cfg); err != nil {
 		return HighlightResult{}, err
 	}
 
-	low, high, err := highlight(&b, ctx.Inner(), ctx.Type(), attributes, cfg)
+	low, high, err := highlight(&b, code, lang, attributes, cfg)
 	if err != nil {
 		return HighlightResult{}, err
 	}

markup/highlight/highlight_integration_test.go

@@ -80,6 +80,50 @@ HighlightCodeBlock: Wrapped:{{ $result.Wrapped  }}|Inner:{{ $result.Inner }}
 	)
 }
 
+// See issue 11872.
+func TestCodeblockWithTypeOverride(t *testing.T) {
+	t.Parallel()
+
+	files := `
+-- hugo.toml --
+disableKinds = ['home','rss','section','sitemap','taxonomy','term']
+[markup.highlight]
+noClasses = false # to reduce size of assertion string
+-- content/p1.md --
+---
+title: p1
+---
+§§§go {style=monokai class=my-class tabWidth=8}
+i = 42
+§§§
+-- content/p2.md --
+---
+title: p2
+---
+§§§{style=monokai class=my-class tabWidth=8}
+i = 42
+§§§
+-- layouts/page.html --
+{{ .Content }}
+-- layouts/_markup/render-codeblock.html --
+{{- $opts := dict }}
+{{- if not (transform.CanHighlight .Type) }}
+	{{- $opts = dict "type" "text" }}
+{{- end }}
+{{- $result := transform.HighlightCodeBlock . $opts }}
+{{- $result.Wrapped -}}
+`
+
+	b := hugolib.Test(t, files)
+
+	b.AssertFileContent("public/p1/index.html",
+		`<div class="highlight my-class"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go"><span class="line"><span class="cl"><span class="nx">i</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">42</span></span></span></code></pre></div>`,
+	)
+	b.AssertFileContent("public/p2/index.html",
+		`<div class="highlight my-class"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">i = 42</span></span></code></pre></div>`,
+	)
+}
+
 // Issue #11311
 func TestIssue11311(t *testing.T) {
 	t.Parallel()

tpl/transform/transform.go

@@ -94,21 +94,50 @@ func (ns *Namespace) Emojify(s any) (template.HTML, error) {
 	return template.HTML(helpers.Emojify([]byte(ss))), nil
 }
 
-// Highlight returns a copy of s as an HTML string with syntax
+// Highlight returns a copy of CODE as an HTML string with syntax
 // highlighting applied.
-func (ns *Namespace) Highlight(s any, lang string, opts ...any) (template.HTML, error) {
-	ss, err := cast.ToStringE(s)
+//
+//	transform.Highlight CODE [LANG] [OPTIONS]
+//
+// LANG is optional; it can also be set via the type option in OPTIONS, which
+// makes this work the same way as HighlightCodeBlock.
+func (ns *Namespace) Highlight(s any, args ...any) (template.HTML, error) {
+	code, err := cast.ToStringE(s)
 	if err != nil {
 		return "", err
 	}
 
-	var optsv any
-	if len(opts) > 0 {
-		optsv = opts[0]
+	var lang string
+	var opts any
+
+	switch len(args) {
+	case 0:
+	case 1:
+		// A single argument is either OPTIONS (a map or option string) or LANG.
+		if _, ok := args[0].(map[string]any); ok {
+			opts = args[0]
+		} else {
+			var arg string
+			if arg, err = cast.ToStringE(args[0]); err != nil {
+				return "", err
+			}
+			if strings.Contains(arg, "=") || strings.Contains(arg, ",") {
+				opts = arg
+			} else {
+				lang = arg
+			}
+		}
+	case 2:
+		if lang, err = cast.ToStringE(args[0]); err != nil {
+			return "", err
+		}
+		opts = args[1]
+	default:
+		return "", errors.New("transform.Highlight: expects at most 3 arguments")
 	}
 
 	hl := ns.deps.ContentSpec.Converters.GetHighlighter()
-	highlighted, err := hl.Highlight(ss, lang, optsv)
+	highlighted, err := hl.Highlight(code, lang, opts)
 	if err != nil {
 		return "", err
 	}

tpl/transform/transform_integration_test.go

@@ -103,6 +103,34 @@ disableKinds = ['page','rss','section','sitemap','taxonomy','term']
 	b.Assert(err.Error(), qt.Contains, "error calling highlight: invalid Highlight option: 0")
 }
 
+// transform.Highlight: LANG is optional and may be set via the type option, and
+// the code option overrides CODE — consistent with transform.HighlightCodeBlock.
+// See issue 11872.
+func TestHighlightTypeAndCodeOptions(t *testing.T) {
+	t.Parallel()
+
+	files := `
+-- hugo.toml --
+disableKinds = ['page','rss','section','sitemap','taxonomy','term']
+[markup.highlight]
+noClasses = false
+-- layouts/home.html --
+lang:{{ transform.Highlight "i = 42" "go" }}
+type:{{ transform.Highlight "i = 42" (dict "type" "go") }}
+code:{{ transform.Highlight "" (dict "type" "go" "code" "i = 42") }}
+`
+
+	b := hugolib.Test(t, files)
+
+	want := `<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go"><span class="line"><span class="cl"><span class="nx">i</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">42</span></span></span></code></pre></div>`
+
+	b.AssertFileContent("public/index.html",
+		"lang:"+want,
+		"type:"+want,
+		"code:"+want,
+	)
+}
+
 // Issue #11884
 func TestUnmarshalCSVLazyDecoding(t *testing.T) {
 	t.Parallel()