Upgrading from Jekyll to Ghost

I have already explained in my last post the reasons for moving away from Jekyll running Github Pages.

This post describes the steps I took to move everything over to Ghost, focusing on the content and not the networking / domain part of things.

Creating the Ghost blog

I used a one-click install droplet from Digital Ocean. Two minutes and it was easy <3.

Moving the posts over to Ghost

The most important part of moving over is of course to get all your posts back up. For this, I needed to extract the Jekyll posts and get them in a format that Ghost could understand.

Getting the content in Ghost format

There are several converters available online to convert all your Jekyll posts in Ghost format. Here is one written in Python. Here is another one written in Node. I used both with success :).

They are fairly easy to use, simply copy the folder containing your posts locally and let the script do the work for you.

Converting the output to V2 Ghost format

There is an issue with the converters listed above : They create a dump that is written in Ghost V1 format. However, the latest Ghost version is now V2. To be able to ingest the dump, you need to upgrade it.

For this, I have:

• Installed an old version of Ghost locally(npm install ghost-cli@latest -g ;ghost install 1.25.6)
• Uploaded the dump
• Upgraded the Ghost instance to the latest version(ghost update --v1 ;ghost update)
• Exported the data again

The process was fairly easy with the ghost-cli tool, and everything worked within 10 minutes.The last step is finally to import the V2 dump into your Ghost instance. You can remove your local instance of ghost, now.

Updating the images links

I very seldom use images in my posts, but I know that the converter don't take those. The most recommended option to fix this limitation is to zip all your images and upload them in your ghost instance, and then update the links in your posts directly. I have not done this but you can find guides online that explain how to do it.

Getting your redirects working

Jekyll uses a yyyy/mm/name-of-the-file format by default to create urls. Ghost uses something based on the title of the post and not the filename.Because my blog has been online for a while, it was important for me that the former URLs still let people access the correct post and not a 404 page.

I found no easy solution to generate those. So being lazy, I created a script for it. You can find it here.

The script takes every markdown file in the list, and creates a relation between :

• The Jekyll format : n/yyyy/mm/filename_without_date/
• The Ghost format: /title_of_article_in_yaml
• Some additional magic is needed (Filtering of the special characters (such as '()!,-'), Removing multi-spaces, Converting spaces to -)

This was enough to convert most of my redirect properly. As you can read on the README in the repo, there are still some caveats. But it was close enough for me to call it a day. I got a JSON file with a list of redirects that I could upload in Ghost.

Theming

I was not amazed by the default Ghost theme, and browsed the marketplace to find something better. I decided to roll for Horace which seemed visually appealing while staying simple. The marketplace is full of beautiful things, I definitely recommend browsing it.

The theme was almost directly ready to be used. I only changed the main color to make it mine, and remove the comments (I prefer taking things on Twitter or email). MyColor.space has been a tremendous help to me find another color that would work with the rest of the theme. Just pick the color you want to change and the tool will offer possible replacements.

Work in progress

• I lost my tags when converting. Not sure why. Not a big problem for me, but might be worth investigating for you before you jump
• Very old posts of mine were not written in Markdown, but in HTML with code banners. Those don't play well when converting. I had to manually fix those (and some are still left, for example this one). <!--kg-card-begin: image-->

• Ghost allows you to use images to illustrate the title of your posts. This is obviously something that you will have to do manually, should you want it. To save myself some time, I focused on the 2 first pages of my list of posts, and on the most read articles that I have.

Final note

All in all, a lengthy but not complicated process. I lost some stuff on the way, but given the history of the blog, and the different stages it went through I think it went ok.

I wish there was a more complete and up to date converter from Jekyll to Ghost though, all options seem to not have been updated in a couple years (maybe because they work well enough as is....). But at least a converter to V2 would be nice.

Cheers!