perl.com Hugo Upgrade Strategy Suggestions

upgrade-hugo.md

Hugo 0.59.1 to Latest Version Upgrade Guide

Looking at the Hugo version jump from 0.59.1 (released in September 2019) to the current latest version (0.147.5, released May 2025), you'll need to handle several major breaking changes that accumulated over 5+ years of development.

Major Breaking Changes to Address

1. Configuration File Changes

Hugo now prefers hugo.toml over config.toml as the primary configuration file name. While config.toml still works as a fallback, updating to hugo.toml aligns with current best practices and avoids potential conflicts in multi-framework setups.

2. Markdown Renderer Switch (Critical Change)

The most significant change affects the Markdown processing engine. Hugo switched from Blackfriday to Goldmark as the default Markdown handler in version 0.60.0. This change can break existing content rendering.

Immediate migration options:

• Temporary workaround: Add this to your config to keep using Blackfriday:

  [markup]
  defaultMarkdownHandler = "blackfriday"

• Long-term solution: Blackfriday was completely removed in v0.100.0, so you'll need to migrate content to work with Goldmark

Common Goldmark compatibility issues:

• Raw HTML is disabled by default in Goldmark - enable with:

  [markup.goldmark.renderer]
  unsafe = true

• Different handling of line breaks, smart quotes, and code block formatting
• Changes in how lists and blockquotes interact

3. Template Function Deprecations

Recent versions deprecated .Site.IsServer in favor of hugo.IsServer. You'll need to update any templates using the old syntax.

4. Content Organization Changes

There were breaking changes around version 0.80 affecting how section content renders on homepages. The old pattern of using {{ range (where .Pages "Type" "supplier") }} may no longer work and requires adding sections as params in the config file.

Recommended Upgrade Strategy

Given the scope of changes, I'd suggest this phased approach:

1. Backup everything first
2. Update Hugo binary to latest version
3. Rename config.toml to hugo.toml
4. Add Blackfriday fallback temporarily to your config
5. Test build - fix any immediate template errors
6. Gradually migrate to Goldmark by testing content rendering differences
7. Update deprecated template functions as warnings appear

Additional Considerations

• One developer reported needing to update 80 out of 700 Markdown files when migrating from Blackfriday to Goldmark
• Consider using a diff tool to compare HTML output before and after the upgrade
• The switch to Goldmark does fix some long-standing issues with smart quotes and list formatting

Configuration File Examples

Basic hugo.toml with Blackfriday fallback

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My Hugo Site'

[markup]
defaultMarkdownHandler = "blackfriday"

Goldmark configuration with unsafe HTML enabled

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My Hugo Site'

[markup]
defaultMarkdownHandler = "goldmark"

[markup.goldmark.renderer]
unsafe = true

Testing Your Migration

1. Compare HTML output: Diff the public/ directory before and after upgrade
2. Check for warnings: Hugo will display deprecation warnings during build
3. Validate content rendering: Pay special attention to:
   • Code blocks with syntax highlighting
   • Raw HTML embedded in Markdown
   • Smart quotes and special characters
   • List and blockquote formatting

The upgrade is definitely manageable, but the Markdown renderer change will likely require the most attention. Starting with the Blackfriday fallback gives you time to methodically test and fix content rendering issues.