gohugoio/hugo · error

goldmark

Error message

goldmark: %s

What it means

Thrown by markup_config.Config.Init() when the Goldmark sub-config's own Init() returns an error. The underlying error is reformatted with the 'goldmark:' prefix using %s (string coercion, not %w wrapping), so errors.Is/As will NOT unwrap into it. Today Goldmark.Init() only runs Parser.Init() which migrates the deprecated AutoHeadingIDType field to AutoIDType, so a real failure here almost always points to a malformed [markup.goldmark] table that mapstructure decoded into an unexpected shape.

Solutions

1. Inspect the full error chain printed after 'goldmark:' to see the concrete sub-message, then fix that specific Goldmark key in your config.
2. Run `hugo config` or `hugo --renderToMemory` to validate config parsing in isolation.
3. Compare your [markup.goldmark] block against the current Default in markup/goldmark/goldmark_config/config.go and remove/rename any deprecated keys.
4. If you do not need custom Goldmark settings, delete the [markup.goldmark] section entirely to fall back to defaults.

Example fix

# before
[markup.goldmark.parser]
  autoHeadingIDType = "github"   # renamed to autoIDType in 0.144.0

# after
[markup.goldmark.parser]
  autoIDType = "github"

// Validate the goldmark sub-config shape before calling Decode/Init.
import "github.com/gohugoio/hugo/markup/goldmark/goldmark_config"

func validateGoldmark(g goldmark_config.Config) error {
    switch g.Parser.AutoIDType {
    case "", goldmark_config.AutoIDTypeGitHub, goldmark_config.AutoIDTypeGitHubAscii, goldmark_config.AutoIDTypeBlackfriday:
    default:
        return fmt.Errorf("goldmark.parser.autoIDType %q invalid", g.Parser.AutoIDType)
    }
    return g.Init()
}

err := markupCfg.Init()
if err != nil && strings.HasPrefix(err.Error(), "goldmark:") {
    // config-shape problem; surface a clear message and the offending section
    return fmt.Errorf("invalid [markup.goldmark] config: %w", err)
}

When it happens

Trigger: Calling markup_config.Decode(cfg) with a hugo.yaml/toml that has a [markup.goldmark] block whose keys decode into incompatible types; specifically any value that breaks the Parser.Init migration or, in custom builds, any added Goldmark validation. Fires during site config load (hugo.Config from config.Provider).

Common situations: Upgrading Hugo across a major version where Goldmark config keys were renamed (e.g. AutoHeadingIDType -> AutoIDType in 0.144.0, typographer bool->struct in 0.112.0, footnote bool->struct in 0.151.0) and an old config still uses the legacy shape in a way the migrator in normalizeConfig did not catch. Hand-editing config with a typo or wrong nesting level under [markup.goldmark.parser].

Related errors

• project config…
• project config markup.goldmark.renderHooks.link.useEmbedded…
• failed to init config
• rst
• --appendPort=false not supported when in multihost mode

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

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