Import your Jekyll posts and articles into Ghost

So you want to leave Jekyll and import your articles into Ghost? Here's an easy to follow step by step guide to do this in a matter of minutes.

And yes, the title of this article clearly states Importing Jekyll into Ghost. But before I switched to Medium I actually had all my Posts in Jekyll sites.

So making the switch from Medium to Ghost is not really straight forward. There are a lot of import tools to get your articles from WordPress, Jekyll, Blogger, Tumblr. But You have to be brave to import Medium to Ghost. So I decided to do the import via an Jekyll site. I only wanted to import the Python articles and I had all those articles backed-up in Jekyll Markdown posts.

Existing Ghost Export Plugins

There are a few ways you can import your current site into your new Ghost setup. WordPress is the most easiest (there is an official plugin for it) the rest … wel… take a leap of faith and hope for the best.

Official export plugins

WordPress users can use the official Ghost WordPress Plugin to export data into a Ghost-compatible JSON format that can be imported quickly and easily in Ghost Admin.

Non-official export plugins

The Jekyll to Ghost Plugin exports your Markdown files into a format that can be easily imported into Ghost. Yes, this plugin will help you do that, though there are some limitations. It doesn’t handle static pages, and it doesn’t do anything with images. You’ll have to copy those over yourself and manually adjust any URL differences.

This plugin was actually built by reverse-engineering the WordPress exporter plugin to match the JSON file it outputs.

Jekyll export to Ghost plugin installation

The export plugin installation for Jekyll is quite simple. Follow the next steps and some more, when you need authors, on the Jekyll to Ghost Plugin page.

  1. Clone the repo and drop the jekylltoghost.rb file into your Jekyll site’s _plugins directory
  2. Run jekyll build.
  3. There should now be a ghost_export.json file in the _site directory.
  4. Follow the Ghost guide here to convert the HTML block into Mobiledoc (this is what the new Ghost blog accepts).

  5. Core command: migrate json html /path/to/your/import.json -> this line will generate a new JSON file with Mobiledoc entries added.

Download the JSON file, (optional) edit the users section, and import it through the Ghost Lab tab.

But hold on!!! What about Jekyll. Well you cannot use a newer version like Jekyll 4.0

The easiest way to do the export import is to create a new jekyll site, put your posts in it, install the plugin and do a Jekyll Build. Please follow the next steps.

First… open a terminal on your OS.

  1. Create a folder to put you new Jekyll site in. mkdir new_jekyll on mac and linux. Sorry, if you are a windows user, start using a real OS!
  2. Go to the folder cd new_jekyll
  3. Do a jekyll new . (don’t forget the . //dot//)
  4. Now copy all your to be exported posts into _posts
  5. Okay… let’s check what version Jekyll you have with jekyll -version
  6. If it states jekyll 4.0.0 go to the next step, if lower like jekyll 3.8.6 go to step 12
  7. Open your Gemfile with nano Gemfile
  8. Remove the line gem "jekyll", "~> 4.0.0"
  9. Add the line gem "jekyll", "~> 3.8.6"
  10. Save and Quit Nano Control+X Y enter
  11. Do a Bundle install
  12. Did you put the jekylltoghost.rb file into your Jekyll site’s _plugins directory?
  13. Do jekyll build or bundle exec jekyll build

That’s it!

So just remember the export plugin will not work on Jekyll > 3.8.6

The clean Jekyll install is just to make sure no strange error occur.

Handling errors on migrate json html from Jekyll to Ghost

So… exporting the json was a breeze for me.. took me about 1 hour to get Jekyll right but who is counting time. (well I am as Im nearly 45 when I write this article)

But had had some nasty errors on the migrate json html import.json part. To be able to import your articles you have to migrate your HTML and Markdown articles to Mobiledoc

Mobiledoc is a standardised JSON-based document storage format, which forms the heart of publishing with Ghost. In order to import content into Ghost, it must first be converted to mobiledoc.

Although mobiledoc is a JSON format, the mobiledoc field in the import file should be serialised into a string, which can be done by calling JSON.stringify().

Ghost’s importer is not able to accept other formats, such as HTML or markdown. Instead, there are tools available for converting from these formats into mobiledoc prior to importing.

The easiest way to convert HTML to mobiledoc is to generate a Ghost JSON file with html fields containing your content for each post instead of mobiledoc. You can then use Ghost’s standalone migration tool to convert the html field to a mobiledoc field.

  1. Requires Node.js v10 installed locally
  2. npm install @tryghost/migrate -g – install the migration tooling
  3. migrate json html /path/to/your/import.json – will convert the HTML fields in your JSON file
  4. The tool will output a path to a converted JSON file – use this to import your content
  5. Run npm uninstall @tryghost/migrate -g to cleanup

Now, I had a problem with my node version on my Mac. It seemed to have a old installed version (with the installer). And I could not install a newer version with brew.

So… I had to take some steps.

  1. brew uninstall node
  2. which node
  3. sudo rm -rf /usr/local/bin/node
  4. sudo rm -rf /usr/local/lib/node_modules/npm/
  5. brew doctor
  6. brew cleanup --prune-prefix

If you are brave and want to run this at once.

brew uninstall node;
which node;
sudo rm -rf /usr/local/bin/node;
sudo rm -rf /usr/local/lib/node\_modules/npm/;
brew doctor;
brew cleanup --prune-prefix;

Now you can reinstall node by

brew install node

and a

brew link --overwrite node

Not so brave? You can try to download an installer package: .pkg on mac. Prefer the latest stable version.

Here is the link: Node.js

This package will eventually overwrite the previous version and set environment variables accordingly. Just run the installer and its done within a few clicks.

Still having problems? It could be that the overwriting of the link for node does not work.

If you are comfortable with using root-rights and setting correct rights to files and folders do a

sudo rm '/usr/local/include/node/common.gypi'

and a

sudo chown -R $(whoami) $(brew --prefix)/\*

It the above manual I got everything to work. Please use terminal statements with care, I’m not responsible when you are breaking things. If you do not feel comfortable with the terminal and setting rights, installing programs and removing files and folders, then don’t!

Did you find this article valuable?

Support Theo van der Sluijs by becoming a sponsor. Any amount is appreciated!