v0.11 Migration Guide

Welcome to HugoBlox v0.11! 🚀 This release is a major milestone designed to align your site with modern Hugo best practices and the latest architectural standards.

As Hugo continues its rapid evolution—introducing smarter modules, faster build engines, and more robust configuration patterns—we’ve taken this opportunity to rebuild HugoBlox’s core. We’re doing the heavy lifting now so your sites stay compatible, performant, and secure as the Hugo ecosystem moves forward.

Embracing the Future (Breaking Changes)

To support these latest Hugo standards and ensure long-term stability, v0.11 introduces a clean break from legacy v0.10 configuration. We know migrations can be a friction point, but this shift is necessary to ensure HugoBlox remains a cutting-edge tool rather than a legacy burden.

The Great News: We’ve built automatic migration scripts to handle the heavy lifting for you! Most users can migrate their entire site in just a few minutes.

---

Why v0.11? (The Modern Hugo Era)

Hugo is moving fast, and v0.11 is our commitment to keeping you on the leading edge. By adopting the latest patterns driven by the Hugo team, we’ve unlocked a superior developer experience:

• ⚡️ Latest Hugo Ecosystem Support: Fully optimized for Hugo’s newest performance engines. Say goodbye to “deprecated” warnings and hello to faster builds.
• 🧩 Standardized Configuration: Everything now lives under a unified hugoblox namespace, aligning with Hugo’s modern module and configuration architecture.
• 🏷️ Intuitive Naming: We’ve updated terminology (e.g., identity instead of branding) to be more descriptive and user-friendly, matching 2026 industry standards.
• 🚀 Zero Legacy Debt: By removing workarounds for obsolete Hugo versions, the codebase is now leaner, more stable, and easier for you to extend.
• 🛡️ Future-Ready Tools: This structure is the foundation for our new HugoBlox Studio and the next generation of visual editing experiences.

---

Prerequisite: Install the CLI 🛠️

To make the migration process as smooth as possible, we recommend installing the HugoBlox CLI. This tool automates many of the migration tasks and helps you manage your site more efficiently.

Install it globally via NPM:

npm install -g hugoblox

The CLI is accessible via the hugoblox command or the convenient hbx alias. It provides a variety of valuable functions, including migrating to new versions and updating modules:

• 🚀 hbx migrate: Automatically migrate your project to newer versions.
• 📦 hbx upgrade: Quickly update your HugoBlox modules to the latest versions.
• 🛠️ hbx doctor: Check your local environment for common issues.

---

1. Module (and Repo) Rename

We renamed both the repo and the core modules. You need to update your go.mod and module imports.

Repo path: github.com/HugoBlox/kit → github.com/HugoBlox/kit

Module paths:

• Core: .../modules/blox-tailwind → .../modules/blox
• Analytics: .../modules/blox-analytics → .../modules/analytics
• Netlify: .../modules/blox-plugin-netlify → .../modules/integrations/netlify
• Slides (Reveal): .../modules/blox-plugin-reveal → .../modules/slides

Automated Upgrade (Recommended)

The easiest way to upgrade your modules to the new v0.11 paths is using the CLI:

hbx upgrade

This will automatically update your go.mod and module imports to the latest versions.

Manual Upgrade

If you prefer to update your modules manually, follow these steps:

1. Open go.mod

   Locate your go.mod file in the root of your project.

2. Update repo + module paths

   Replace old paths with the new ones. For example:

   Before:

   require (
       github.com/HugoBlox/kit/modules/blox-tailwind v0.0.0
       github.com/HugoBlox/kit/modules/blox-plugin-netlify v0.0.0
       github.com/HugoBlox/kit/modules/blox-plugin-reveal v0.0.0
   )

   After:

   require (
       github.com/HugoBlox/kit/modules/blox v0.11.0
       github.com/HugoBlox/kit/modules/integrations/netlify v1.2.1
       github.com/HugoBlox/kit/modules/slides v1.2.5
   )

3. Update dependencies

   hugo mod get -u github.com/HugoBlox/kit/modules/blox@v0.11.0
   hugo mod get -u github.com/HugoBlox/kit/modules/integrations/netlify@v1.2.1
   hugo mod get -u github.com/HugoBlox/kit/modules/slides@v1.2.5
   hugo mod tidy

4. Update module imports in config/_default/modules.yaml

   Update your module import paths to the new github.com/HugoBlox/kit modules.

   Remove any modules you’re not using from the example below:

   imports:
     - path: github.com/HugoBlox/kit/modules/integrations/netlify
     - path: github.com/HugoBlox/kit/modules/blox
     - path: github.com/HugoBlox/kit/modules/slides

---

2. CMS & Editing

Decap CMS Deprecated

Decap CMS (formerly Netlify CMS) is deprecated in v0.11. This decision was made because Netlify is no longer maintaining the project, leading to unpatched bugs and compatibility issues.

New Recommended Workflow

We now recommend HugoBlox Studio as the primary way to edit and manage your HugoBlox site.

Studio is a VS Code extension tailored specifically for HugoBlox, offering:

• 🎨 Visual Editor - Configure your site without touching YAML
• ✨ Live Preview - See changes instantly
• 🤖 Fix-It Bot - Automatically fix content issues

Tip

Download HugoBlox Studio to get started with the new visual editing experience.

---

3. Author Profile Migration

Migrate your author profiles from content/authors/ to the new data-driven system at data/authors/.

1. Run the migration command:

   hbx migrate v0.11.0-authors

2. What it does:

   • Creates data/authors/ directory
   • Converts content/authors/<slug>/_index.md to data/authors/<slug>.yaml
   • Moves avatars to assets/media/authors/<slug>.jpg
   • Updates author references in your content files
   • Archives the old folder to content/authors.backup/

---

4. Event Content Migration

Migrate your event pages to standard Hugo dates and improved front matter structure.

1. Run the migration command:

   hbx migrate v0.11.0-events

2. What it does:

   • Renames content/event/ directory to content/events/ (plural)
   • Updates front matter to fix conflicts with Hugo’s date
   • Maps old parameters to new standard ones:
     • date (start) → event_start
     • date_end → event_end
     • all_day → event_all_day
     • event → event_name
     • publishDate → date (standard Hugo publish date)

Manual Event Migration Details

If you prefer to migrate events manually or need to troubleshoot, here is the breakdown.

Why the change? (Standardizing with Hugo)

In earlier versions, events used Hugo’s standard date field to represent the event start time. While this worked for simple sites, it conflicted with Hugo’s core sorting and archiving logic, which expects date to be the page publication date.

v0.11 restores Hugo’s intended behavior. By using namespaced parameters like event_start, we ensure your events work perfectly with Hugo’s native features (like RSS feeds and sitemaps) without needing complex workarounds.

v0.11 introduces clear, namespaced parameters:

Old Parameter	New Parameter	Notes
date	event_start	The actual start time of the event
date_end	event_end	The end time
all_day	event_all_day	Boolean
event	event_name	Name of the conference/venue
publishDate	date	Standard Hugo page date (used for sorting)

Example

Before (v0.10):

title: "My Talk"
event: "HugoConf"
date: 2030-06-01T13:00:00Z       # Confusing: acts as event start
date_end: 2030-06-01T14:00:00Z
publishDate: 2023-01-01T00:00:00Z # Actual page date

After (v0.11):

title: "My Talk"
date: 2023-01-01T00:00:00Z       # Standard Hugo date
event_name: "HugoConf"
event_start: 2030-06-01T13:00:00Z
event_end: 2030-06-01T14:00:00Z
event_all_day: false

---

5. Configuration Migration (params.yaml)

What’s Changed?

Major Restructuring

Single Namespace

Everything lives under hugoblox: for clarity and brand protection.

User-Friendly Names

identity, search, header instead of branding, features.search, header.navbar.

Domain Organization

Grouped by what it IS, not where it appears on the page.

Schema-Driven

JSON Schema enables VSCode autocomplete and validation.

Structure Comparison

v0.10 (Old)

hugoblox:
  branding: {...}
  theme: {...}

appearance: {...}      # Legacy
marketing:             # Generic
  seo: {...}
  analytics: {...}
header:
  navbar: {...}        # Nested
footer:
  copyright: {...}
features:              # Dumping ground
  math: {...}
  search: {...}
locale: {...}

v0.11 (New)

hugoblox:
  schema: "2.0"
  identity: {...}      # Clear
  theme: {...}
  typography: {...}
  layout: {...}
  header: {...}        # Flattened
  footer: {...}
  copyright: {...}     # Own section
  seo: {...}
  content: {...}
  search: {...}        # First-class
  comments: {...}
  analytics: {...}
  verification: {...}
  repository: {...}
  locale: {...}
  security: {...}
  privacy: {...}
  debug: {...}
  pro: {...}

Quick Configuration Migration

1. Backup your current config

   cp config/_default/params.yaml config/_default/params.yaml.backup

2. Replace params.yaml with v0.11 structure

   Download the template for your site type:

   • Academic CV
   • Blog
   • Documentation
   • Landing Page
   • Resume

3. Fill in your settings from the backup

   Use the mapping tables below to find where your old settings go.

4. Test your site

   pnpm dev <your-template>
   # Visit http://localhost:1313

5. Verify everything works

   Check:

   • ✅ Site name in navbar/footer
   • ✅ Theme colors applied
   • ✅ Analytics tracking
   • ✅ Search functionality

Complete Parameter Migration Map

Identity & Branding

v0.10 Path	v0.11 Path	Notes
hugoblox.branding.name	hugoblox.identity.name	Renamed section
hugoblox.branding.site_title	hugoblox.seo.title	Moved to SEO (optional override)
hugoblox.branding.organization	hugoblox.identity.organization	Renamed section
header.navbar.logo.text	hugoblox.identity.name	REMOVED - Use identity
marketing.seo.org_name	hugoblox.identity.organization	REMOVED - Use identity
marketing.seo.site_type	hugoblox.identity.type	Now in identity
marketing.seo.description	hugoblox.identity.description	Now in identity
marketing.seo.twitter	hugoblox.identity.social.twitter	Now in identity

New in v0.11:

• identity.tagline - Short headline for your site
• identity.type - Choose: person, organization, or local_business

Theme & Appearance

v0.10 Path	v0.11 Path
appearance.mode	hugoblox.theme.mode
appearance.color	hugoblox.theme.colors.primary
appearance.theme_day / theme_night	hugoblox.theme.pack.light / pack.dark
appearance.font	hugoblox.typography.font
appearance.font_size	hugoblox.typography.size
hugoblox.theme.ui.*	hugoblox.theme.surfaces.*

Header & Navigation

v0.10 Path	v0.11 Path
header.navbar.enable	hugoblox.header.enable
header.navbar.block	hugoblox.header.style
header.navbar.fixed_to_top	hugoblox.header.sticky
header.navbar.show_search	hugoblox.header.search
header.navbar.show_mode_toggle	hugoblox.header.theme_toggle
header.navbar.show_theme_picker	hugoblox.header.theme_picker
header.navbar.show_translations	hugoblox.header.language_switcher
header.navbar.align	hugoblox.header.align
header.navbar.button.*	hugoblox.header.cta.*

Footer & Copyright

v0.10 Path	v0.11 Path
footer.block	hugoblox.footer.style
footer.show_translations	hugoblox.footer.language_switcher
footer.text	hugoblox.footer.text
footer.copyright.*	hugoblox.copyright.*

Analytics

v0.10 Path	v0.11 Path
marketing.analytics.google_analytics	hugoblox.analytics.google.measurement_id
marketing.analytics.google_tag_manager	hugoblox.analytics.google_tag_manager.container_id
marketing.analytics.plausible	hugoblox.analytics.plausible.domain
marketing.analytics.fathom	hugoblox.analytics.fathom.site_id
marketing.analytics.pirsch	hugoblox.analytics.pirsch.site_id
marketing.analytics.microsoft_clarity	hugoblox.analytics.clarity.project_id
marketing.analytics.baidu_tongji	hugoblox.analytics.baidu.site_id

Features

v0.10 Path	v0.11 Path
features.math.enable	hugoblox.content.math.enable
features.comment.provider	hugoblox.comments.provider
features.search.*	hugoblox.search.*
features.repository.*	hugoblox.repository.*
features.avatar.shape	hugoblox.layout.avatar_shape
features.privacy_pack.enable	hugoblox.privacy.enable
publications.citation_style	hugoblox.content.citations.style

Locale & Other

v0.10 Path	v0.11 Path
locale.*	hugoblox.locale.*
security.*	hugoblox.security.*
i_am_a_sponsor	hugoblox.pro.hide_attribution
affiliate_ref	hugoblox.pro.affiliate_code

Migration Examples

Personal Academic Website

v0.10 (Old)

hugoblox:
  branding:
    name: "Dr. Jane Smith"
  theme:
    mode: system
    pack: minimal

appearance:
  mode: dark
  font: serif

marketing:
  seo:
    description: "AI researcher..."
    twitter: "janesmith"
  analytics:
    google_analytics: "G-XXXXXXXXXX"

header:
  navbar:
    show_search: true

features:
  math:
    enable: true

locale:
  date_format: "Jan 2, 2006"

v0.11 (New)

hugoblox:
  schema: "2.0"

  identity:
    name: "Dr. Jane Smith"
    type: person
    description: "AI researcher..."
    social:
      twitter: "janesmith"

  theme:
    mode: system
    pack: minimal

  typography:
    font: serif
    size: md

  layout:
    radius: md
    spacing: comfortable
    avatar_shape: circle

  header:
    enable: true
    style: navbar
    sticky: true
    search: true
    theme_toggle: true

  footer:
    style: minimal

  copyright:
    notice: "© {year} {name}"
    license:
      type: cc
      allow_derivatives: false
      share_alike: true
      allow_commercial: false

  content:
    math:
      enable: true
    citations:
      style: apa

  analytics:
    google:
      measurement_id: "G-XXXXXXXXXX"

  locale:
    date_format: "Jan 2, 2006"
    time_format: "3:04 PM"
    address_format: en-us

Research Lab Website

v0.10 (Old)

hugoblox:
  branding:
    name: "Stanford AI Lab"
    organization: "Stanford University"

marketing:
  seo:
    site_type: Organization

header:
  navbar:
    button:
      text: "Join Us"
      url: "/careers/"

features:
  comment:
    provider: "giscus"
    giscus:
      repo: "lab/website"

v0.11 (New)

hugoblox:
  schema: "2.0"

  identity:
    name: "Stanford AI Lab"
    organization: "Stanford University"
    type: organization
    tagline: "Advancing AI for humanity"

  header:
    cta:
      enable: true
      text: "Join Us"
      url: "/careers/"

  comments:
    enable: true
    provider: giscus
    giscus:
      repo: "lab/website"
      repo_id: "..."
      category: "Comments"
      category_id: "..."

New v0.11 Features

Auto-Detected Assets

No more configuring file paths! Just place these files in assets/media/:

Filename	Purpose
logo.{svg,png,jpg}	Site logo (auto-detected)
social.{png,jpg}	Social share image (auto-detected)
icon.{svg,png}	Favicon (auto-detected)

Before:

header:
  navbar:
    logo:
      image: "logo.svg"

After:

# Nothing needed! Just place logo.svg in assets/media/

Richer Identity

Tell your story with new fields:

hugoblox:
  identity:
    name: "Dr. Jane Smith"
    type: person              # NEW: person | organization | local_business
    tagline: "AI Researcher"  # NEW: Short headline
    description: "Full bio"   # For SEO and social sharing
    social:
      twitter: "janesmith"    # Used for Twitter Cards

Enhanced Search

Search is now a first-class feature:

hugoblox:
  search:
    enable: true
    suggestions:              # NEW: Trending searches
      - "Publications"
      - "Research Areas"
    quick_actions:            # NEW: Quick links in search
      - label: "Contact"
        url: "/contact/"
        icon: "envelope"

Pro Features

New licensing system with environment variable validation:

hugoblox:
  pro:
    hide_attribution: false   # Requires HUGO_BLOX_LICENSE env var
    affiliate_code: ""        # Join affiliate program

Note

Even with a Pro subscription, you can keep hide_attribution: false to support the open-source project! Many researchers choose to keep the attribution visible.

Field-by-Field Guide

Required: Site Identity

Minimal valid v0.11 config:

hugoblox:
  schema: "2.0"
  identity:
    name: "Your Name"

Everything else has sensible defaults!

Common Settings

Most researchers only need to configure:

hugoblox:
  schema: "2.0"

  identity:
    name: "Dr. Jane Smith"
    type: person
    description: "AI researcher at Stanford..."

  theme:
    mode: system
    pack: minimal

  typography:
    font: serif              # Academic feel
    size: md

Advanced: Theme Customization

hugoblox:
  theme:
    mode: dark
    pack:
      light: minimal         # Mix & match!
      dark: dracula
    colors:
      primary: "#6366f1"
      secondary: "#10b981"
      neutral: "slate"

Advanced: Analytics Setup

hugoblox:
  analytics:
    google:
      measurement_id: "G-XXXXXXXXXX"
    plausible:
      domain: "yoursite.com"

  verification:
    google: "verification-code"

Special Cases

Local Business Schema

If your site represents a business with a physical location:

hugoblox:
  identity:
    type: local_business

  seo:
    location:
      address:
        street: "123 Main St"
        city: "San Francisco"
        region: "CA"
        postal_code: "94105"
        country: "US"
      coordinates:
        latitude: 37.7749
        longitude: -122.4194
      phone: "+1-415-555-0100"

Comments System

Giscus

hugoblox:
  comments:
    enable: true
    provider: giscus
    giscus:
      repo: "username/repo"
      repo_id: "R_..."
      category: "Comments"
      category_id: "DIC_..."

Disqus

hugoblox:
  comments:
    enable: true
    provider: disqus
    disqus:
      shortname: "yoursite"

”Edit This Page” Links

hugoblox:
  repository:
    enable: true
    url: "https://github.com/username/repo"
    branch: main
    content_dir: content

Removed/Changed Features

No Longer Needed

These parameters have been removed because the features are always enabled or not implemented:

Removed	Why
features.math.renderer	Only KaTeX supported
features.search.provider	Only Pagefind supported
marketing.seo.local_business_type	Use identity.type instead

Renamed for Clarity

Old Name	New Name	Reason
block (header/footer)	style	Avoid confusion with page blocks
fixed_to_top	sticky	Standard web terminology
show_* prefix	Feature name	Simpler (e.g., search not show_search)
button	cta	More descriptive

Pro Subscription Changes

v0.10 (Honor System)

i_am_a_sponsor: true

v0.11 (License Validation)

Step 1: Get your Pro license key:

HUGO_BLOX_LICENSE=4e5fb6f4-c253-...

Step 2: Add to your hosting platform (Netlify, Vercel, etc.):

Environment Variables → HUGO_BLOX_LICENSE = [your-key]

Step 3: Configure params.yaml:

hugoblox:
  pro:
    hide_attribution: true   # Requires valid license

Tip

Get Pro: hugoblox.com/pro
Already a subscriber? Check your confirmation email for your license key, or reach out in the Pro Discord channel.

VSCode Autocomplete

(In progress - available upon release)

Enable autocomplete and validation in VSCode:

# yaml-language-server: $schema=https://hugoblox.com/schema/v2/params.schema.json

hugoblox:
  schema: "2.0"
  # Now you get autocomplete! ✨

Or add to .vscode/settings.json:

{
  "yaml.schemas": {
    "https://hugoblox.com/schema/v2/params.schema.json": "config/**/params.yaml"
  }
}

---

Troubleshooting

Build Fails After Migration

1. Check the schema version is set:

   hugoblox:
     schema: "2.0"  # Required!

2. Validate your YAML syntax:

   • Check indentation (2 spaces)
   • No tabs allowed
   • Colons followed by space

3. Check required fields:

   • hugoblox.identity.name is required
   • All other fields are optional

4. Look for typos:

   • theme_toggle not theme_chooser
   • sticky not fixed_to_top
   • style not block (for header/footer)

Site Looks Different

• Colors changed? Check theme.colors.primary matches your old appearance.color
• Font changed? Verify typography.font - serif is Roboto Slab, sans is Inter
• Spacing different? Try layout.spacing: "compact" or "spacious"

Analytics Not Working

Check the new nested structure:

hugoblox:
  analytics:
    google:                    # Note the nesting
      measurement_id: "G-XXX"  # Not just a string anymore

Attribution Still Shows (Pro Users)

You need both:

1. Environment variable: HUGO_BLOX_LICENSE=your-license
2. Config setting: pro.hide_attribution: true

Verify the env var is set in your hosting platform and redeploy.

---

Getting Help

Community Discord

Join for help, tips, and community support

discord.gg/z8wNYzb

GitHub Discussions

Ask questions and share solutions

Discussions

Pro Support

Pro subscribers get priority support

Join Pro Discord Channel

Documentation

Complete reference and examples

docs.hugoblox.com

---

---

Changelog

v0.11.0 Latest

Breaking Changes:

• Renamed: Repo HugoBlox/kit → HugoBlox/kit (Update go.mod)
• Removed: Backward compatibility with v0.10 params
• Restructured: Everything under hugoblox namespace
• Renamed: branding → identity
• Renamed: header.navbar → header (flattened)
• Renamed: footer.copyright → copyright (own section)
• Renamed: marketing.* → Split across identity, seo, analytics, verification
• Renamed: features.* → Distributed to relevant sections

New Features:

• ✨ Schema versioning (hugoblox.schema: "2.0")
• ✨ Auto-detected assets (logo, social image, favicon)
• ✨ identity.tagline field
• ✨ identity.type for Schema.org
• ✨ Enhanced search configuration
• ✨ Pro license validation system
• ✨ JSON Schema for VSCode autocomplete
• ✨ Comprehensive documentation

Improvements:

• 🎯 User-friendly naming conventions
• 📦 Single namespace for brand protection
• 🚀 Cleaner codebase for faster development
• 📱 VSCode extension ready
• 🔐 Secure Pro licensing with environment variables

---

Migration Support

Need help migrating? Reach out in Discord or GitHub Discussions. The community is here to help!