Migrating from Hugo to GAX: What Changes and What Stays

Hugo and GAX are both Go static site generators, but they make different trade-offs. Hugo is a mature system with deep taxonomy configuration and a large theme catalog. GAX is simpler, with pre-built themes and a content structure that works without heavy setup.

If you are considering a move from Hugo to GAX, this guide covers what carries over, what needs rewriting, and how to plan the migration so you do not lose search rankings along the way.

What Carries Over

Markdown content. Your .md files with frontmatter will mostly work as-is. GAX uses YAML frontmatter, the same format Hugo uses.

Folder structure. Both use content/ for Markdown, a templates folder for layouts, and public/ or site/ for static assets.

Deployment targets. Both output a static folder you can deploy to Vercel, Netlify, Cloudflare Pages, GitHub Pages, or a VPS.

Markdown syntax. Headings, lists, links, images, code blocks, and tables are standard Markdown and work the same in both.

URL structure. File-based routing works similarly in both generators, so /blog/my-post/ style URLs usually carry over without redirects.

What Needs Rewriting

Template syntax. Hugo uses Go templates with pipelines and shortcodes. GAX uses .gax layouts with simpler includes and loops. If your Hugo site uses complex template logic, that will need to be rewritten.

Theme files. Hugo themes are not compatible with GAX. You will need a GAX theme or a custom layout.

Shortcodes. Hugo shortcodes do not carry over. If your content uses shortcodes for image galleries, callouts, or embedded components, those will need to be replaced with Markdown or partials.

Taxonomy configuration. Hugo has powerful taxonomy configuration. GAX uses auto collections — simpler to set up, but less configurable for unusual structures.

Site configuration. Hugo's config.toml or hugo.yaml does not map directly to GAX's _data/config.yaml. Navigation, menus, and site settings need to be recreated in the GAX format.

How to Plan the Migration

1. Audit your current site. List the layouts, shortcodes, and taxonomy features you actually use. Most sites use far less than they think.

2. Pick a GAX theme. Start with a theme that already includes the layouts you need. This is faster and safer than porting a Hugo theme.

3. Move content in batches. Start with blog posts, then pages, then docs. Check each batch after moving it.

4. Recreate configuration. Set up navigation, footer, brand, and social links in _data/config.yaml.

5. Verify SEO output. Check that sitemap, RSS, and canonical tags are generated correctly before going live.

6. Deploy in parallel. Keep the old site live while testing the new one on a staging URL. Switch DNS only after confirming everything works.

Protecting SEO During Migration

A migration can hurt rankings if URLs change without redirects or if metadata is lost. To protect SEO:

  • Keep the same URL structure where possible. File-based routing usually allows this.
  • Add redirects for any URL that changes. Most static hosts support a redirects file.
  • Preserve titles and descriptions from your Hugo frontmatter.
  • Submit the new sitemap in Google Search Console after the switch.
  • Do not delete the old site immediately. Keep it live for a few weeks after DNS switch so crawlers can catch up.

When Not to Migrate

If your Hugo site uses complex taxonomy, heavy shortcode usage, or custom Go template logic, migration may cost more than it saves. Hugo is a mature platform and is not going anywhere.

GAX is a better fit if:

  • You want a finished theme instead of assembling one
  • You want simpler template syntax
  • You do not use shortcodes or complex taxonomy
  • You want a smaller, simpler codebase to maintain

For a fair comparison of the two, read GAX vs Hugo.

Getting Help

A custom migration from Hugo, Jekyll, or 11ty is available as a service.

FAQ

Can I migrate from Hugo to GAX without losing SEO?

Yes, if you keep the same URL structure, preserve titles and descriptions, add redirects for changed URLs, and submit the new sitemap. The migration process is straightforward but needs care.

Do Hugo themes work with GAX?

No. Hugo themes use Hugo's template syntax and are not compatible with GAX. You need a GAX theme or a custom layout.

Can I keep my Markdown files as-is?

Mostly yes. GAX uses YAML frontmatter, the same format as Hugo. You may need to adjust a few fields that are Hugo-specific.

What happens to my Hugo shortcodes?

Shortcodes do not carry over. Replace them with Markdown, GAX partials, or plain HTML where needed.

Is it worth migrating from Hugo to GAX?

Only if GAX solves a specific problem for you — simpler theme editing, built-in SEO defaults, or a finished premium theme. If Hugo works for your site, there is no urgent reason to switch.

How long does a Hugo to GAX migration take?

For a small blog or documentation site, a few days. For a large site with custom templates and shortcodes, one to two weeks. Custom migration help is available through contact.