A WordPress site that has been live for a few years is mostly URLs. Every post someone linked to, every service page sitting on page one, every PDF a sales rep still emails. Rebuild that site on HubSpot CMS and the design work is the easy half. The half that decides whether traffic survives the move is the mapping: which old address goes to which new one, loaded before the DNS changes, checked after it does.
This is a guide to that half. Inventorying the URLs you have, building the map, loading it into HubSpot's redirect tool, and the checks that tell you within a week whether anything is bleeding. It assumes you are moving pages and a blog onto a HubSpot-hosted domain and keeping the same domain name.
If you would rather hand the mapping to someone who does it as a job, that is the shape of our WordPress to HubSpot migration work. If you are building the new site yourself, the two things worth reading alongside this are our guide to fixing Core Web Vitals on HubSpot CMS, since a migration is the one moment you get to set page weight from scratch, and the HubSpot CMS themes that give you the templates to land the content in.
Inventory every URL before you design anything
You cannot map what you have not listed. Pull the inventory from several sources, because each one misses something the others catch:
- The WordPress export. Tools > Export gives you an XML file containing posts, pages, and their permalinks. This is your structural spine.
- A crawl of the live site. Any crawler that follows internal links will surface attachment pages, paginated archives, and old landing pages nobody remembers publishing.
- Search Console. Export the last twelve months of pages by impressions and clicks. This is the ranking list, and it decides priority.
- Your analytics. Pages with real sessions but no organic impressions are usually linked from email or ads, and those links do not update themselves.
- The existing redirect table. Whatever plugin has been quietly redirecting old URLs for years still needs to keep doing that job.
Join those into one spreadsheet keyed on URL, with impressions and clicks alongside. The result sorts itself: a short head of URLs carrying most of the traffic, and a long tail of thin archive pages. The head gets a hand-written destination each. The tail gets pattern rules or a considered dead end.
Build the map, one row per old URL
The map has three columns you will use at import time: the original URL, the destination URL, and the redirect style. Fill the destination with the closest equivalent page on the new site. Closest means the page that answers the same question, so a retired service page points at the service that replaced it rather than at the homepage. Redirecting a wide set of retired pages to the homepage is a common shortcut, and search engines tend to treat those as soft 404s.
Two more columns cost nothing: the impressions the old URL earned, so you know what to check first after cutover, and a note explaining any decision you will not remember in three months.
What HubSpot's URL structure does that WordPress's does not
WordPress puts pages, posts, categories, tags, and date archives in one address space governed by a permalink setting. HubSpot separates content into groups, and the group decides the URL. Website pages sit at whatever slug you give them. Blog posts sit under the root URL of the blog they belong to, so a post on a blog rooted at /blog lives at /blog/post-slug. Move a post to a different blog and its URL updates to include the new blog's root.
Two consequences for your map. First, a WordPress permalink structure that puts dates in the path, like /2024/03/post-name, is not something HubSpot reproduces. Those posts land at /blog/post-name and every dated URL needs a redirect. Second, HubSpot will not let two pieces of content hold the same URL. If the URL you want is already in use, you change the other content first.
One HubSpot behaviour works in your favour during the build. Changing the slug of a published page or post creates a redirect from the old URL to the new one automatically. That covers the tidying you do after launch. It does not cover the WordPress URLs, which HubSpot has never seen.
Moving the posts
HubSpot imports a WordPress blog two ways, and they do not bring the same things. The XML export carries the title, post body including inline images, URL, publish date, author, tags and categories, status, meta description, and featured images; PDFs linked in posts and images inside gallery tags are left behind. Connecting to the blog over the WordPress REST API carries the title, post body, SEO title, author, publish date, featured image, categories and tags, and meta description, but not the URL and not the publish status, and author images only where they sit in the post body. Either way, the gaps move by hand.
Before you export, confirm that internal links and image sources in your post bodies are absolute. Relative paths break on import, and this is far cheaper to fix before the move than after it.
Categories, tags, and archives
HubSpot's blog organises posts by tag, with no parent-child nesting. WordPress categories and tags both arrive as tags, so any hierarchy you had flattens. Listing pages exist for tags and authors at /blog/tag/tag-name and /blog/author/author-name, so those two archive types have somewhere to point.
Date archives and paginated category archives have no equivalent. Check their impressions before deciding. Most of the time they earn nothing and can be left to 404, which is a legitimate answer for a page that no longer exists. Where a category archive does rank, the honest destination is a HubSpot tag listing page covering the same subject, or a website page you build for the topic.
Loading the redirects into HubSpot
Redirects live in settings, under Content > Domains & URLs > URL Redirects, and the import accepts a CSV whose columns you map to HubSpot's fields during upload. The constraints that shape your file:
- A maximum of 500 redirects can be added or updated in one bulk operation, so a large map ships in batches.
- URLs uploaded in bulk are capped at 140 characters. Longer ones go in by hand.
- Errors in the file prevent the entire import, including the rows that are formatted correctly. Validate before you upload, and read the error spreadsheet HubSpot posts to your account notifications when an import fails.
- Permanent (301) is the default style and the one Google recommends for a move. Temporary (302) and proxy (305) styles exist for other jobs.
- By default a redirect applies whether or not the original URL has a trailing slash, and whether it starts with http:// or https://.
- Where more than one rule matches an original URL, the rule with the lowest priority number wins.
- Redirects work for domains connected to and hosted in HubSpot. Anything still served from the old host has to be redirected there.
- Propagation can take up to 48 hours.
That last point about hosting is the one that catches people mid-cutover. Until DNS points the domain at HubSpot, the redirect table is inert.
Flexible redirects for the patterned tail
Dated permalinks and old subdirectories are pattern problems, and HubSpot's flexible redirects handle them without a row per URL. An asterisk captures the remainder of a path and a colon captures a single component up to the next delimiter, and both are referenced in the destination inside curly brackets. HubSpot's own example maps http://www.example.com/posts/*rest-of-url to http://blog.example.com/posts/{rest-of-url}, and a component pattern like /:year/:month/:day/:post-name can be recomposed in any order on the destination side.
Use these for the tail and hand-write the head. A pattern rule that silently swallows a URL you meant to send somewhere specific is hard to spot later.
Canonicals and hreflang
Every page and post in HubSpot has a canonical URL field under Settings > Advanced in the editor. Carry over any custom canonical you set in WordPress, and check the ones you did not set deliberately, since a stale canonical pointing at the old site keeps the new one out of the index.
For multilingual sites, build the translations as multi-language variations of the same content rather than as unrelated pages. HubSpot then emits hreflang alternates across the group through the standard header includes, so the template has to be outputting those. That is what marks the variants as alternates instead of duplicates.
Images, forms, and tracking
Imported inline and featured images land in HubSpot's file manager. The gaps to fill by hand are the ones the importer skips: linked PDFs, gallery images, and anything referenced from a theme file rather than from post content.
Forms are a rebuild. WordPress form plugins store submissions in the WordPress database, and those records need exporting before the site comes down. On the HubSpot side the tracking code is included automatically on HubSpot-hosted website pages, landing pages, and blog pages, so page views and form submissions start flowing without an install step. Third-party tags injected through a WordPress plugin need re-adding, and a migration is a reasonable moment to drop the ones nobody reads.
Cutover and the first 30 days
Once DNS points at HubSpot, work through this in order:
- Crawl the new site and separately crawl your list of old URLs. Every old URL should return a single 301 to a live page. Chains and loops show up here.
- Check the sitemap at
/sitemap.xml. HubSpot adds live website pages and blog posts automatically. Landing pages are added by hand, in settings, under Content > Domains & URLs > Sitemap. Sitemap changes take up to 30 minutes to appear. - Submit the new sitemap in Search Console and drop the old one.
- Use the Change of Address tool only if the domain name itself changed. A move that keeps the domain and changes paths does not use it.
- Watch Search Console coverage and the impressions of your top twenty old URLs daily for the first two weeks, then weekly. A dip in the first days is normal while Google recrawls. A dip that keeps deepening past two weeks means a mapping problem, and the 404 report usually names it.
- Keep the redirects in place. Google's guidance is at least a year, which is how long it takes for signals to move and for other sites to update their links.
The measure of a good migration is that nobody outside the team notices one happened. Every old address still lands somewhere sensible, the rankings hold their positions through the recrawl, and the only visible change is the site itself.