gohugoio/hugo · error

goldmark: %s

Error message

goldmark: %s

What it means

`markup_config.Config.Init` initializes each markup engine's sub-config and wraps any Goldmark configuration error with the "goldmark:" prefix. It's a pass-through wrapper: the real cause is whatever `Goldmark.Init()` rejected in the `markup.goldmark` section of the site configuration, surfaced at config-load time before the build starts.

Source

Thrown at markup/markup_config/config.go:52

	// The configuration used by code highlighters.
	Highlight highlight.Config

	// 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)

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Read the wrapped message after "goldmark:" — it names the actual invalid option — and fix that key in the [markup.goldmark] config section.
2. Compare your [markup.goldmark] block against the current Hugo docs for your installed version.
3. Temporarily remove the [markup.goldmark] section to confirm the defaults load, then reintroduce keys one at a time.

// validate the goldmark section shape before building
var mc markup_config.Config
if err := mapstructure.WeakDecode(v.GetStringMap("markup"), &mc); err != nil {
    return fmt.Errorf("invalid [markup] config: %w", err)
}

cfg, err := markup_config.Decode(v)
if err != nil {
    // wrapped as "goldmark: ..." — report the offending markup.goldmark key and abort the build
    return fmt.Errorf("site config error: %w", err)
}

When it happens

Trigger: Loading a site config whose `[markup.goldmark]` tree contains an invalid value that Goldmark's own Init rejects — for example an invalid `renderHooks`/extension setting or an enum-style option outside its allowed values. The exact inner message follows the "goldmark:" prefix.

Common situations: Hand-edited hugo.toml with a typo'd or out-of-range goldmark option; upgrading Hugo across versions where goldmark config keys were renamed or validation tightened; copying goldmark snippets from docs for a newer Hugo release into an older one.

Related errors

• project config markup.goldmark.renderHooks.image.useEmbedded
• project config markup.goldmark.renderHooks.link.useEmbedded
• redirects must have either From or FromRe set
• failed to create config from result: %w
• failed to create config: %w

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