gohugoio/hugo · error

invalid value for syntaxHighlight

Error message

invalid value for syntaxHighlight: %q

What it means

Returned by rst_config.Config.Init() when SyntaxHighlight is not one of the three allowed values "short", "long", "none". These map directly to rst2html's --syntax-highlight argument; an invalid value would be passed to the external tool, so Hugo rejects it at config-load time rather than at render time.

Solutions

1. Set [markup.rst] syntaxHighlight to "short", "long" (default), or "none".
2. Omit the key to get the default "long".
3. Restart Hugo to confirm the config decodes cleanly.

Example fix

# before
[markup.rst]
syntaxHighlight = "html"

# after
[markup.rst]
syntaxHighlight = "none"

func validRstSyntaxHighlight(v string) bool {
    switch v {
    case "short", "long", "none":
        return true
    }
    return false
}

func isRstSyntaxHighlight(v string) bool {
    switch v {
    case "short", "long", "none":
        return true
    }
    return false
}

if err := rstCfg.Init(); err != nil {
    // default to "long" and retry if the user-supplied value was invalid
    rstCfg.SyntaxHighlight = "long"
}

When it happens

Trigger: Setting markup.rst.syntaxHighlight (or the RST Config struct) to any string other than "short", "long", or "none", then calling Config.Init() (via markup_config.Decode during Hugo startup).

Common situations: Old tutorials referencing values like "html"/"html5" that rst2html no longer accepts; case typo ('Long'); trailing whitespace; copy-pasting the Pygments style name instead of the rst2html mode.

Related errors

• rst
• config needs a filename
• empty related config provided
• failed to decode languages config
• failed to decode options for resource

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/430035f79a6f8b2e. Report an issue: GitHub.

Appendix: 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 52c9bd7908)