gohugoio/hugo · error

rst: %s

Error message

rst: %s

What it means

Thrown by markup_config.Config.Init() when c.RST.Init() fails, prepending 'rst:' via %s (not %w, so the cause is not unwrappable). RST.Init() validates the syntaxHighlight field, so in practice this error is almost always the wrapped form of error 444 ('invalid value for syntaxHighlight'). It surfaces during markup config decode at startup.

Source

Thrown at markup/markup_config/config.go:55

	// Table of contents configuration
	TableOfContents tableofcontents.Config

	// Configuration for the Goldmark markdown engine.
	Goldmark goldmark_config.Config

	// Configuration for the AsciiDoc external markdown engine.
	AsciiDocExt asciidocext_config.Config

	// Configuration for the reStructuredText external markdown engine.
	RST rst_config.Config
}

func (c *Config) Init() error {
	if err := c.Goldmark.Init(); err != nil {
		return fmt.Errorf("goldmark: %s", err)
	}
	if err := c.RST.Init(); err != nil {
		return fmt.Errorf("rst: %s", err)
	}
	return nil
}

func Decode(cfg config.Provider) (conf Config, err error) {
	conf = Default

	m := cfg.GetStringMap("markup")
	if m == nil {
		return
	}
	m = hmaps.CleanConfigStringMap(m)

	normalizeConfig(m)

	err = mapstructure.WeakDecode(m, &conf)
	if err != nil {
		return

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Set [markup.rst] syntaxHighlight to one of: "short", "long" (default), or "none".
2. Remove the [markup.rst] block to accept the default "long".
3. Re-run `hugo` to confirm the config loads.

Example fix

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

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

// Pre-validate RST config before Decode/Init.
func validateRST(syntaxHighlight string) error {
    switch syntaxHighlight {
    case "", "short", "long", "none":
        return nil
    }
    return fmt.Errorf("rst.syntaxHighlight %q must be short|long|none", syntaxHighlight)
}

if err := markupCfg.Init(); err != nil {
    if strings.HasPrefix(err.Error(), "rst:") {
        // point user at the [markup.rst] syntaxHighlight value
    }
    return err
}

When it happens

Trigger: Setting [markup.rst] syntaxHighlight to anything other than "short", "long", or "none" in hugo.toml/yaml/json. Fires from markup_config.Decode -> Config.Init during Hugo bootstrap.

Common situations: Copying an RST config snippet from an outdated tutorial that uses a value like "html" or "html5"; typo such as 'Long' (capitalized) or 'short ' (trailing space); confusing the rst syntaxHighlight knob with Hugo's general code highlighter config.

Related errors

• invalid value for syntaxHighlight: %q
• role name cannot be empty
• version name cannot be empty
• language name cannot be empty
• invalid module config for %q: both source and target must be

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