Today's topic is migration! Maybe you've just discovered Ghost and are ready to move your WordPress blog. Or maybe you've decided the time is right to move your newsletter from Substack. Or SendFox. Or Joomla. Or... There are lots of possibilities.

So, let's talk site migrations. We do a lot of these, but in this post, we'll focus on some of the decisions we make when doing a migration. Whether you're running your own migration, having a concierge migration, or hiring us, here's what you should consider.

Do you own a domain?

If you own yourdomain.com, you're in great shape to move the domain to the new host. If you currently blog at something like yourdomain.substack.com, then you can't move that domain. [Update: But maybe you can redirect from Substack? Yeah, I was surprised, too!] Advice: Buy a domain that matches your branding, and use it! (You should have done this when you first started building your first site, but now is better than later.) Then if you move, you can take your URLs with you! The rest of this post assumes you already own a domain.

Google Search Console

Before you start (several days to a week before - like, as soon as you start thinking about it), make sure you set your site up with Google Search Console. That'll let you monitor for problems as you're doing your move, like suddenly missing pages or broken links. I'm a fan of AHREFs - even their free plan does a great job of scanning for suddenly missing pages. If you do your move right, you won't have any, but it's nice to get a report if something's wrong, before you lose too much page rank!

DNS

DNS (Domain Name Service) is how your browser finds the server that hosts your website. When you type www.spectralwebservices.com into your browser, your computer consults a DNS server to find out what server to ask for that webpage. When you move your site from one host to another, you'll need to update your DNS to point your domain at your new host.

Broken DNS means that requests for your website won't get there, even if your website's server is working perfectly and ready to respond. Here's what you need to think about while moving:

Caching

DNS is cached. Your browser caches where the server is, your router caches where the server is, your internet service provider caches where the server is, etc. That caching makes DNS fast (important, since you want visitors to get to your site rapidly when they ask for it), but it means you can get 'stale' DNS information. The parameter that controls DNS caching is TTL (time-to-live). The TTL might be set to an entire day, which means that after you change your DNS, you could be waiting an entire day (sometimes more) before all the caches have expired and you're consistently getting the right answer. That's hard to troubleshoot. So, before you start moving your site, log in to your DNS provider (which is probably your domain registrar) and set the TTL to something short, like five minutes. Then wait a couple days before making DNS changes, so that you know they'll be live immediately. (OK, technically in five minutes. Close enough!) When all your new changes are perfect, then you can put your TTLs back to something more normal like 24 hours.

MX records

If you don't have any email sent to [email protected], you can ignore this part.

If you have email that gets delivered to the domain you're going to move, there are two major possibilities:

1) You have MX records (which you'll find in your DNS entries). MX records tell email servers where to deliver your email to. If those records exist, then you can move your website's DNS records. Just leave the MX records alone! [If you have mail service provided by your current host but you plan to cancel that account after you move your website, you need to make a new plan for email before you cancel the old account, but it's probably OK to move your DNS.]

2) You don't have MX records. That means that email sent to [email protected] is getting delivered to the A or CNAME record server. When you move webservers, you're going to change that DNS entry, which is 100% guaranteed going to break your email unless you do something about it. Don't touch your DNS until you've made a plan for email, in this case.

Content

You should move all of your content. No, seriously, move all of it. Read on for how and why!

How to move content

Ghost has some built in migration functionality, which you can find in the migration documentation.

If the migration directions look too complicated to do yourself, the Ghost Pro migration team declines it, or you aren't signing up for an eligible plan, feel free to get in touch. We can move anything.

Why to move content

Short answer: Broken links are bad! You don't want Google serving broken links in search results, and you don't want visitors who find a link to your site linked somewhere else on the internet to get a broken link when they try to visit you.

Google decides what sites to include in search results, and in what order, based on what it knows about your content, and what it knows about sites that link to you. If you break those inbound links, you'll lose those "votes" for your content being useful. And if you remove content, you lose the opportunity to have Google send a visitor to your site for that content.

Old content is still good content in most cases. If it's outdated, add a disclaimer at the top (or make sure your migration includes moving the original publication date). The only time I'd delete content is if it was embarrassing, or a problem (like an outdated price list). And even then, it'd be better to update the content rather than just deleting it.

If you're running a local news site, you should definitely move the content! Local news is precious as archival material. Don't dump it!

So, yeah, move it all.

Broken links, part 2

You're moving your content, because you've decided that breaking links is bad. But how do you avoid breaking links?

It depends a bit on what format the links are. If the links are something like yourcurrentsite.com/blog/the-name-of-the-post or yourcurrentsite.com/the-name-of-the-post, then you could write a routes.yaml file to keep your posts at the same URL, rather than redirecting. Matching the existing routing avoids redirections, which can be preferable for ranking with Google. (Google will follow a redirect, but they're reported to be less desirable/reduce page rank versus going directly to the right link.)

If the links are something more complicated or you want to change the formatting of the URLs, you may need a redirects.yaml file. A redirects file can map any old urls onto the new ones. The format is detailed in the Ghost documentation. Some useful examples:

301:
  ^/2012/08/random-thoughts-about-our-hacking-situation.html/ /random-thoughts-about-our-hacking-situation/

301:
  ^\/blog\/([a-z0-9-]+)\/$: /$1

301:
  ^\/[0-9]+\/[0-9]+\/([a-z0-9-_]+)\/$: /$1/

301:
  ^\/p\/((?![0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\/$)[A-z0-9-_.]+)\/$: /$1

Subscribers

If you have current newsletter subscribers, you'll want to import them into Ghost. Ghost will take a CSV upload. All fields except email address are optional.

If your users are current subscribers, you can import them with their Stripe subscriber ID. That'll allow you to link their existing Stripe accounts and subscriptions. (If those subscriptions are Ghost subscriptions because you're migrating from another Ghost site, they'll get assigned to the correct subscription. If the subscriptions aren't originally from Ghost, they'll get correctly marked for renewal date and monthly/yearly price, but will be automatically assigned to your lowest active tier. (Two options for this: (1) Create one tier, import those subscribers only, then deactivate the first tier, create the next tier, import those subscribers, etc, and then reactivate all the tiers. (2) Use the Stripe API to recreate each subscriber's subscription as the correct Ghost subscription.)

If you're importing from Substack, be sure to read this note about getting Substack fees removed before you start!

Images

So, let's talk images. Generally, your export file is going to contain HTML documents (or something that renders to it) for each post and page. Within that document, any images are just URLs, that your browser loads. As a result, most exports do NOT include the images.

After you think you've gotten your posts imported, it's going to be really important to check that your images are there, before you switch over your DNS. Don't just check that the page looks OK. Inspect (right click and choose 'inspect' from the menu) and make sure that the URL of the image is not the URL of your old site. Your want those URLs pointed at the new site, or some third party site. Otherwise, what can happen is that everything looks fine until you turn off the old site, and then suddenly, all the images are broken, and maybe you don't have access to the old site any more, making fixing the problem harder.

So, make sure you move your images! I often end up running a script that downloads existing images linked from each post, uploads them to Ghost, gets the new URL for each image, edits the post html to point to the correct URL, and then imports that html to Ghost. Unless there's hotlink protection messing up my plans. Then it just takes longer.

Hey, before you go... If your finances allow you to keep this tea-drinking ghost and the freelancer behind her supplied with our hot beverage of choice, we'd both appreciate it!

Buy me a tea ☕️