Updating Hugo Blox Websites

Keep your Hugo Blox website current with new features, fixes, and enhancements by updating Hugo, Go, and Hugo Blox modules. Regular updates ensure compatibility and leverage improvements like better blocks or styling. This guide outlines a Git-based workflow to test changes safely before deployment.

Before You Begin: Back Up Your Site

Always back up your site directory before updating to protect your content and config. For instance, cp -r site site.bak makes an exact copy of the site directory and all its contents and names the copy site.bak. Here’s the process in practical terms, assuming you’re working on a system like Linux, macOS, or Windows with a Unix-like terminal (e.g., Git Bash):

• Open Your Terminal:

  • On Linux or macOS, just open the Terminal app.
  • On Windows, you might use something like Git Bash, WSL (Windows Subsystem for Linux), or PowerShell with a Unix emulator installed.

• Navigate to the Right Location:

  • Use the cd command to move to the directory that contains your site folder. For example, if your website files are in /home/user/projects/site, type:

    cd /home/user/projects
    

  • You can check you’re in the right place by typing ls (or dir on some Windows setups) to see if site is listed.

• Run the Command:

  • Type cp -r site site.bak and press Enter.
  • If site exists, the system will create a new directory called site.bak in the same location and copy everything from site into it.

• Verify the Backup:

  • After the command finishes, you can check that site.bak exists and contains the same files as site. Use ls (or dir) to see the new directory, or explore it manually:

    ls -l
    

  • You could also compare the contents with a tool like diff if you want to be extra sure:

    diff -r site site.bak
    

  (If there’s no output, they’re identical.)

• Things to Keep in Mind:

  • Permissions: You need write access to the directory where you’re creating site.bak. If you get a “permission denied” error, you might need to run the command with sudo (e.g., sudo cp -r site site.bak) or adjust permissions.
  • Existing Destination: If site.bak already exists, cp -r will copy site into site.bak rather than overwriting it, unless you force an overwrite with the -f flag (cp -rf site site.bak). Be cautious—overwriting could erase an older backup.
  • Space: Make sure you have enough disk space for the duplicate. If site is large, site.bak will take up just as much room.
  • Naming: .bak is just a convention to indicate a backup. You could name it anything, like site_backup_2025 or site_copy.

Choosing Your Update Approach

Two mindsets exist for keeping Hugo Blox current, each suited to different goals. Choose based on whether you prioritize content or new features.

Hugo Blox Release-Driven Approach

• When to Update: Update only when a new Hugo Blox template releases (e.g., a new blox-bootstrap version in go.mod). These may align with Hugo updates but often don’t, as Hugo Blox updates independently.
• Process: Follow the steps below per Hugo Blox release, applying all breaking changes since your last update (from Hugo Blox and Hugo).
• Pros:
  • Fewer updates, more focus on content.
  • Updates only when Hugo Blox requires it, avoiding extra work if features aren’t needed.
• Cons:
  • More breaking changes at once, spanning multiple updates, harder to fix if docs lag.
• Best For: Users focused on content over features, waiting for Hugo Blox releases.

Incremental Hugo-Driven Approach

• When to Update: Update often, with Hugo releases (e.g., monthly, like 0.140.0 to 0.141.0), refreshing Hugo Blox modules as needed.
• Process: Follow the steps per Hugo update, fixing smaller breaking changes over time.
• Pros:
  • Smaller, manageable changes per update.
  • Early access to Hugo and Hugo Blox advancements, less hunting for issues.
• Cons:
  • More frequent updates, possibly disrupting content work.
  • Check Hugo Blox compatibility per Hugo version, even without new releases.
• Best For: Users wanting early Hugo and Hugo Blox features, spreading out fixes.

Which Should You Choose?

• Content Focus: If content is key and you don’t need advancements until a Hugo Blox release, use the Release-Driven Approach for less disruption.
• Feature Focus: If you want Hugo and Hugo Blox enhancements sooner with fewer fixes per update, use the Incremental Approach for a current site.

Both use the same steps below—your choice sets the frequency. Check Hugo Releases and Hugo Blox GitHub to monitor updates and decide.

---

Step 1: Prepare Your Website

Preparation ensures a smooth update and a baseline for testing.

Record Current Versions

Document your starting point to track changes and revert if needed:

• Hugo: Run hugo version (Homebrew) or ./bin/hugo version (local) to note the version (e.g., v0.140.0+extended).
• Go: Run go version (e.g., go1.24.0 darwin/amd64).
• Hugo Blox Modules: Open go.mod in your site’s root with VS Code or a text editor. Check require statements (e.g., github.com/HugoBlox/hugo-blox-builder/modules/blox-bootstrap/v5.9.6). Note versions (e.g., v5.9.6) or dev builds (e.g., v0.0.0-20231123212609-31fc15e5b205—cross-reference hashes like 31fc15e in the Hugo Blox GitHub commit log).

Create a Local Hugo Binary (Optional, Recommended for Testing)

To test new Hugo versions without affecting your system-wide install:

• In your site’s root (e.g., /path/to/your/site), create a bin folder:

  mkdir bin
  

• Download the latest Hugo Extended from Hugo Releases (e.g., hugo_extended_0.140.0_darwin-amd64.tar.gz for macOS Big Sur, Intel).

• Extract and move:

  tar -xzf hugo_extended_0.140.0_darwin-amd64.tar.gz
  mv hugo ./bin/hugo
  

• Verify: ./bin/hugo version.

Update .gitignore

Keep the local binary out of Git:

• Edit or create .gitignore in your site’s root:

  /bin/
  

• Commit in VS Code:

  • Open Source Control (Ctrl+Shift+G or Git icon).
  • Stage .gitignore (click +).
  • Commit (message: “Ignore local Hugo binary”) and push to GitHub.

Test Your Current Site

Confirm everything works pre-update:

• Run: hugo server (Homebrew) or ./bin/hugo server (local).
• Open http://localhost:1313 in a browser and check functionality (e.g., pages, Hugo Blox blocks load correctly).

---

Step 2: Update Hugo and Go

Hugo Blox evolves with Hugo, and Hugo uses Go for modules, so updating both ensures compatibility. Hugo updates often (e.g., monthly), while Go updates less (e.g., twice yearly) and should align with Hugo needs.

Create a Test Git Branch

Before updating Hugo and Go, isolate your changes in a Git branch tied to a GitHub Issue:

• In VS Code: Click the branch name in the status bar (e.g., main) > “Create new branch” > name it chore-123-hugo-update (e.g., for GitHub Issue #123: “Update Hugo to 0.141.0”).
• Why This Name? We use type-issue#-description (e.g., feature-123-hugo-update) to link branches to GitHub Issues tracking updates like Hugo/Go changes. Issues manage todos, dates are tracked by Git, and the prefix clarifies purpose (e.g., feature for new updates).
• Feature/Issue-Based Naming Convention:
  • Format: type-issue#-description
    • Structure: type/description or type-issue#-description
    • Type: A prefix indicating the purpose of the branch (e.g., feature, bug, hotfix, chore, docs).
    • Issue# (Optional): A reference to a specific issue or ticket number from a tracking system (e.g., GitHub Issues), if applicable.
    • Description: A concise, hyphen-separated summary of the work (e.g., hugo-update, module-compat).
  • Examples:
    • feature/hugo-update (general feature work)
    • feature-123-hugo-update (tied to GitHub Issue #123)
    • bug/module-compat (fixing a module compatibility issue)
    • hotfix/urgent-deploy (quick deployment fix)
• Core Principles
  • Clarity: The type immediately signals the branch’s intent (e.g., new feature vs. bug fix), while the description provides context.
  • Consistency: Standardized prefixes ensure branches are easily categorized and sorted (e.g., all feature/ branches group together).
  • Integration with Tools: Adding an issue# links directly to issue trackers (e.g., GitHub auto-links #123 in commit messages or PRs).
  • Scalability: Works well for solo projects and scales seamlessly to teams with ticketing systems.
• How It Leverages Git’s Date/Time Tracking

  • Commit Metadata: Git records the creation date and time of each commit (git log --pretty=fuller shows AuthorDate and CommitDate), and branches inherit the timeline of their commits. For example:

    git log --pretty=fuller
    commit 7a8b9c0...
    AuthorDate: Mon Feb 24 12:34:56 2025 -0500
    CommitDate: Mon Feb 24 12:34:56 2025 -0500
    

  • GitHub Insights: On GitHub, the branch list (e.g., under “Branches” tab) shows the last commit date, and PRs display commit timestamps, making manual date prefixes redundant.

  • GitLens: VS Code’s GitLens extension shows commit dates in the timeline, making date prefixes unnecessary.

  • Why Prefixes Over Dates? Git’s built-in date tracking (e.g., git log, GitHub) makes manual date prefixes redundant, focusing on purpose (e.g., feature, bug) for clarity and consistency.

• Best Practices Within This Convention
  • Use Descriptive Types: Stick to common prefixes: feature (new stuff), bug (fixes), hotfix (urgent fixes), chore (maintenance), docs (documentation).
  • Keep Descriptions Short: Use 2-4 words, hyphen-separated (e.g., hugo-update, module-compat-fix).
  • Incorporate Issue Numbers: If using GitHub Issues (even solo), add the ticket number (e.g., feature-123-hugo-update) for linking.
  • Avoid Ambiguity: Be specific (e.g., feature/hugo-141-update vs. feature/hugo-update) if multiple updates occur.
  • Delete Merged Branches: Once merged or abandoned, delete branches (git branch -d feature/hugo-update) to avoid clutter, relying on commit history.

Option 1: Update Local Hugo Binary (Recommended for Testing Hugo Updates)

• Download New Hugo Version:

  • Visit Hugo Releases and download the latest Extended version (e.g., hugo_extended_0.141.0_darwin-amd64.tar.gz).
  • Extract and replace: mv hugo ./bin/hugo.
  • Verify: ./bin/hugo version.

• Update Go (If Required):

  • Check the Release Notes for Hugo for your new version (e.g., 0.141.0).
  • If notes indicate a Go update (e.g., minimum version rise or fixes), upgrade Go via Homebrew:
    • Check current: go version (e.g., go1.24.0 darwin/amd64).
    • Update: brew upgrade go.
    • Verify: go version (e.g., go1.25.0 darwin/amd64).
    • Specific Go Version (If Needed): If Hugo needs a specific Go (e.g., 1.25.0) not latest in Homebrew:
      • Check versions: brew search go (lists go, go@1.24, etc.).
      • Install: brew install go@1.25.0 (if available; @ may not cover latest).
      • Link (if keg-only): brew link --overwrite go@1.25.0 (may need brew unlink go first).
      • If unavailable, see Option 2 methods.
  • If no Go update is noted, Hugo upgrades suffice—for instance, recent Hugo aligns with Go 1.24.0+.

• Test:

  • Run ./bin/hugo server and check http://localhost:1313 for errors or breaking changes.

Option 2: Update via Homebrew (Recommended after Testing Hugo Updates)

• Update Hugo:

  • Run:

    brew upgrade hugo
    

  • Verify: hugo version.

• Update Go (If Required):

  • Check the Release Notes for Hugo for your new version.
  • If a Go update is needed:
    • Check: go version.
    • Update: brew upgrade go.
    • Verify: go version.

• Specific Go Version (If Needed): If Hugo needs a specific Go (e.g., 1.25.0) not latest:

  • Method 1: Switch: brew list --versions go (e.g., go 1.24.0 1.25.0); brew switch go 1.25.0 (if cached).
  • Method 2: Check: brew search go (e.g., go@1.24); Install: brew install go@1.25.0; Unlink: brew unlink go; Link: brew link --overwrite go@1.25.0.
  • Method 3: Tap: brew tap homebrew/cask-versions or brew tap homebrew/core; Search: brew search go; Install: brew install go@1.25.0.
  • Method 4: Find commit at Homebrew Core; Extract: brew extract --version=1.25.0 go my-tap/go; Install: brew install my-tap/go/go@1.25.0.
  • Fallback: Download from golang.org/dl (e.g., go1.25.0_darwin-amd64.tar.gz), extract, use locally (see Local Go Testing).

• Verify: go version matches the needed version.

• If no Go update is noted, skip—existing Go is fine.

• Test:

  • Run: hugo server and check http://localhost:1313 for errors or breaking changes.

---

Step 3: Update Your Modules

Hugo Blox uses modules in go.mod. Updating them adds features and fixes.

Edit go.mod

• Open go.mod in your site’s root with VS Code or a text editor.

• Check current versions (e.g., github.com/HugoBlox/hugo-blox-builder/modules/blox-bootstrap/v5).

• Update to specific versions or latest:

  • TL;DR Quick Update: Use main for dev versions (e.g., github.com/HugoBlox/hugo-blox-builder/modules/blox-bootstrap main). Caution: main may be unstable; check commit logs if prior dev builds were used.
  • Specific Version (Recommended): Use tagged releases (e.g., v5.9.6 from Hugo Blox GitHub “Releases” or module subdirs like modules/blox-bootstrap).

• Example:

  require (
      github.com/HugoBlox/hugo-blox-builder/modules/blox-bootstrap/v5.9.6
      github.com/HugoBlox/hugo-blox-builder/modules/blox-tailwind main
  )
  

Update Modules

• In your test branch (feature-123-hugo-update):
• Run: go mod tidy (uses Homebrew’s Go or ./go/bin/go if local, cleans go.mod and go.sum).
• Optional: hugo mod vendor (downloads modules to _vendor/ for offline use).
• Test: ./bin/hugo server or hugo server.

---

Step 4: Apply Any Breaking Changes

Updates to Hugo or Hugo Blox modules may need manual fixes.

Review Release Notes

• Hugo Blox Release Notes: Check changes since your go.mod version.
• Hugo Release Notes: Note Hugo updates (e.g., syntax) and Go needs.

Update Configuration

• Edit config/_default/ files (e.g., hugo.yaml, params.yaml) for new or renamed params.
• Example: A module might swap theme for appearance—adjust it.

Update Content

• Fix front matter in content/*.md if fields change (e.g., date format).

Test Again

• Run ./bin/hugo server and verify all pages and features (e.g., blocks, styling) work.

---

Step 5: Test Locally

Test your updated site in the test branch:

• Build: ./bin/hugo (or hugo).
• Serve: ./bin/hugo server (or hugo server).
• Check:
  • Browser: http://localhost:1313—ensure content renders right.
  • Terminal: Look for errors (e.g., missing partials, module issues).

---

Step 6: Deploy Your Website

Decide to deploy or revert based on test results.

If the Update is Successful

• Switch to Main Branch:

  • In VS Code, check the status bar (bottom-left). It shows feature-123-hugo-update.
  • Click feature-123-hugo-update > pick main. This returns to your stable version.

• Merge Changes:

  • Go to Source Control (Git icon or Ctrl+Shift+G).
  • Click ... (More Actions) at top-right.
  • Choose “Branch” > “Merge Branch.”
  • Pick feature-123-hugo-update and click it. This merges changes into main.
  • If “Conflicts” appear, open files (e.g., go.mod), fix overlaps, click + to stage, and checkmark to commit.

• Push to GitHub:

  • In Source Control, click ... > “Push” (or click the cloud icon with an up arrow in the status bar).
  • This updates main on GitHub.

If the Update is Unsuccessful (Site Fails to Build)

If the new Hugo, Go, modules, or changes fail (e.g., blank pages, “template not found” errors):

• Check the Problem:

  • Check terminal output from ./bin/hugo or ./bin/hugo server. Note errors (e.g., “module not found”).
  • Visit http://localhost:1313—if broken or missing content, it failed.

• Switch Back to Main Branch:

  • In VS Code, status bar shows feature-123-hugo-update.
  • Click feature-123-hugo-update > pick main. This reverts to your working site.
  • Files (e.g., go.mod, hugo.yaml) return to their original state as main is unchanged.

• Discard Changes in Test Branch:

  • Go to Source Control (Git icon or Ctrl+Shift+G).
  • Click ... > “Branch” > “Delete Branch.”
  • Pick feature-123-hugo-update and click it.
  • If asked “Are you sure?” click “Yes” (or “Delete”). This drops the branch and its changes (e.g., go.mod edits).

• Revert the Hugo and Go Versions:

  • If Local Hugo Binary:
  • If ./bin/hugo updated (e.g., 0.141.0) and you want the old (e.g., 0.140.0):
    • Download from Hugo Releases (e.g., hugo_extended_0.140.0_darwin-amd64.tar.gz).
    • Extract: tar -xzf hugo_extended_0.140.0_darwin-amd64.tar.gz.
    • Replace: mv hugo ./bin/hugo.
    • Verify: ./bin/hugo version matches (e.g., 0.140.0).
  • Since ./bin/ is ignored by Git, this is local only.
  • If Homebrew Hugo:
    • Check: brew list --versions hugo (e.g., hugo 0.140.0 0.141.0).
    • Method 1: Switch: brew switch hugo 0.140.0 (if cached).
    • Method 2: Check: brew search hugo; Install: brew install hugo@0.140.0; Unlink: brew unlink hugo; Link: brew link --overwrite hugo@0.140.0.
    • Method 3: Tap: brew tap homebrew/cask-versions or brew tap homebrew/core; Search: brew search hugo; Install: brew install hugo@0.140.0.
    • Method 4: Find commit at Homebrew Core; Extract: brew extract --version=0.140.0 hugo my-tap/hugo; Install: brew install my-tap/hugo/hugo@0.140.0.
    • Fallback: Download from Hugo, extract, use as ./bin/hugo.
    • Verify: hugo version matches (e.g., 0.140.0).
  • If Go Updated:
    • Check: brew list --versions go (e.g., go 1.24.0 1.25.0).
    • Method 1: Switch: brew switch go 1.24.0 (if cached).
    • Method 2: Check: brew search go; Install: brew install go@1.24.0; Unlink: brew unlink go; Link: brew link --overwrite go@1.24.0.
    • Method 3: Tap: brew tap homebrew/cask-versions or brew tap homebrew/core; Search: brew search go; Install: brew install go@1.24.0.
    • Method 4: Find commit at Homebrew Core; Extract: brew extract --version=1.24.0 go my-tap/go; Install: brew install my-tap/go/go@1.24.0.
    • Fallback: Download from golang.org/dl (e.g., go1.24.0_darwin-amd64.tar.gz), extract, use as ./go.
    • Verify: go version matches (e.g., 1.24.0).

• Test the Original Site:

  • Run ./bin/hugo server (local) or hugo server (Homebrew).
  • Check http://localhost:1313 to confirm your site works.

• Plan Next Steps:

  • Review failed test errors (e.g., terminal or browser).
  • Check Hugo Blox or Hugo notes for fixes (e.g., dependencies, syntax).
  • Start a new branch (e.g., feature-124-hugo-update) linked to a new GitHub Issue.
  • Why This Name? We use feature-issue#-description to tie branches to GitHub Issues tracking updates (e.g., Hugo/Go changes), leveraging Git’s date tracking and issue links for clarity. See Create a test Git branch for details.

Update Deployment Config

• After a successful merge (or keeping main):
• GitHub Pages: Edit .github/workflows/publish.yaml, set WC_HUGO_VERSION to your tested Hugo (e.g., 0.141.0—check Hugo Blox compat).
• Netlify: Update netlify.toml, set HUGO_VERSION (e.g., 0.141.0).
• Deploy: Push to GitHub, monitor Actions > Deploy Site (check log if fails), or verify Netlify via Deploys tab. If you’ve properly tested the changes and updated your site, it should deploy without issues.

---

Troubleshooting

Module Errors

• Run hugo mod get or verify go.mod URLs. Clear cache: hugo --cacheDir ./cache/ and delete ./cache/.

VS Code Go Extension (gopls) Issues

• If using a local ./go (e.g., for Go testing), exclude it:

• Edit settings.json (Cmd+Shift+P > “Preferences: Open Settings (JSON)”):

  "files.exclude": {
  "**/go": true,
  "**/bin": true
  },
  "go.toolsEnvVars": {
  "GOROOT": "/usr/local/Cellar/go/1.24.0/libexec"
  }
  

• Restart VS Code.

More Help

• See Hugo Blox Troubleshooting.

---

Best Practices

1. Backup First: Copy your site folder (e.g., cp -r site site.bak).
2. Test in Branches: Use feature-123-hugo-update to isolate changes, linking to GitHub Issues.
3. Local Hugo Binary: Test Hugo updates with ./bin/hugo for flexibility.
4. Stick with Homebrew Go: Simplifies modules, update per Hugo notes.
5. Track Versions: Note Hugo, Go, and module versions pre/post-update.
6. Apply Sequentially: Update Hugo/Go, modules, configs, test each step.

---