gohugoio/hugo · error

invalid value for syntaxHighlight: %q

Error message

invalid value for syntaxHighlight: %q

What it means

`rst_config.Config.Init` validates the `markup.rst.syntaxHighlight` setting, which is passed through to Docutils as `--syntax-highlight=<value>`. Only "short", "long" (the default, mapping to Pygments' long class names) and "none" are accepted; anything else fails config initialization before any page renders.

Source

Thrown at markup/rst/rst_config/config.go:32

// Package rst_config holds reStructuredText related configuration.
package rst_config

import "fmt"

// Default holds Hugo's default reStructuredText configuration.
var Default = Config{
	SyntaxHighlight: "long",
}

// Config configures reStructuredText.
type Config struct {
	// Configures Pygments syntax highlighting. Valid values are "short", "long" (default) and "none".
	SyntaxHighlight string
}

func (c *Config) Init() error {
	if c.SyntaxHighlight != "short" && c.SyntaxHighlight != "long" && c.SyntaxHighlight != "none" {
		return fmt.Errorf("invalid value for syntaxHighlight: %q", c.SyntaxHighlight)
	}
	return nil
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Set markup.rst.syntaxHighlight to exactly "short", "long", or "none" (lowercase).
2. Remove the key entirely to get the default "long".
3. If you meant to configure Chroma/goldmark highlighting, use the markup.highlight section instead.

Example fix

# before (hugo.toml)
[markup.rst]
syntaxHighlight = "pygments"
# after
[markup.rst]
syntaxHighlight = "short"

switch cfg.SyntaxHighlight {
case "none", "short", "long":
    // ok
default:
    return fmt.Errorf("markup.rst.syntaxHighlight must be none, short, or long; got %q", cfg.SyntaxHighlight)
}

When it happens

Trigger: Setting `markup.rst.syntaxHighlight` in hugo.toml/yaml/json to any string other than "short", "long", or "none" — e.g. "true", "pygments", "Short" (case-sensitive), or an empty string explicitly set.

Common situations: Confusing this Docutils-specific option with Hugo's own `markup.highlight` settings and pasting values like a style name; boolean-style values from assuming it's an on/off switch; capitalization typos in the config file.

Related errors

• redirects must have either From or FromRe set
• failed to create config from result: %w
• failed to create config: %w
• failed to decode %q: %w
• language name cannot be empty

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