Some tips on migrating from Medium

by Michael Bernstein on February 27, 2019

We recently migrated our blog off of the Medium platform and combined it with our existing marketing site. It’s now statically hosted on Netlify, built with Jekyll, and instrumented with Google Analytics. A few people expressed interest in how we achieved this feat – and it is indeed a feat. Getting everything out of Medium and maintaining your links can be a daunting task.

Fortunately a few scripts and Open Source libraries, some clever Netlify features, and some manual editing and CSS’ing can take care of it all for you. We migrated around 60 posts and it took maybe a day’s worth of time spread out over the course of a week or so. Here’s roughly how we did it.

One of our gripes with Medium was that we didn’t want an index chosen for us, we wanted to have our own, chronological index that was just … simple. Because you don’t get an index out of the box, you have to do the cool and unbelievable trick in this blog post to get the list of all of your blog post URLs. Armed with this, you’re ready for step #2.

Step 2: Downloading and converting all of your articles

We used the Node library in this blog post to retrieve our blog posts and convert them from HTML to Markdown. We used the list produced by the first step, more or less rubbing some Python on it to get the job done.

Step 3: Cleaning up the posts

Your posts will come out the other side of this process looking considerably worse than they did on Medium. We had some existing document styles on our website that we were adding our blog to, so we didn’t have to do a ton of extra work there.

Next we cleaned up all of the images by writing a script to extract the image URLs in the posts (we didn’t want to leave our images hosted on the Medium CDN) and download them to our blog git repo. Another simple regex find and replace let us change all of those URLs.

Medium also has several embed formats that don’t translate well in this process. Tweets, videos, and image placement will all need to be manually fixed.

Step 4: Forwarding your old URLs

Medium appends some type of Hash or UUID onto the end of URL slugs. We wanted our new slugs to have a date and title. So we renamed all of the files and then used Netlify’s rewrite and redirect rules to handle all of the redirects for us.

Transparent SSL with LetsEncrypt for the blog subdomain was also easy to add, so now we’ve got a great user experience for our readers with no broken links, thanks to this clever solution.

Step 5: Don’t forget the Analytics

We included Google Analytics in our blog post layout template, and we were delighted to see how things “just worked.” After a few days of spreading old article links around via Twitter and watching the analytics flow through, we were wondering why we ever switched in the first place.

And that’s it!

We’ve now got more control, more insight, and since we never experienced any of the “network effects” from Medium, we don’t miss anything there. The only thing we miss so far are the aesthetics – damn, those posts did look good.