Migrating from Medium to Jekyll and Netlify CMS plugin

At Botsplash, we recently migrated our blogging platform from Medium to self hosted Jekyll site with Netlify CMS plugin to manage the content.

If you are attempting to self-host a blogging platform, then this article will be of interest. Here is what we will explore :

1. Export contents from Medium as zip
2. Create new Jekyll project
3. Import Medium articles to Jekyll
4. Integrate Netlify CMS (along with Github OAuth)
5. Using your custom domain (optional) / for this write up, hosting a sample site using Github pages

1. Export contents from Medium as zip

Medium allows you to export all your personal blog contents.

• Login to your Medium account and navigate to the Settings page.
• Scroll to bottom of the page to “Download your information” section, available above “Membership”.
• Click the “Download .zip” button and then in the next screen, click ‘Export’.

The content will be sent as email in a zipped file format.  Download and unzip the contents to extract comments, claps, bookmarks, drafts etc. Critical item is the “posts” folder.

2. Create new Jekyll project

We will be using Jekyll static website generator engine and an existing blog theme here.  Download the project as zip or clone it in your local system. You will need to remove .git folder if you clone it.

Jekyll is a simple, static and extendable site generator. It is based on Ruby and hence you’ll need to have full Ruby development environment setup. More information can be found here.

After you have the environment setup, go into the project folder using your terminal and enter bundle install command. You might be prompted to enter your admin password. After the required packages are installed, go ahead and run the Jekyll project using the command bundle exec Jekyll serve

You should see your blog running at http://localhost:4000

Copy the ‘posts’ folder from the ‘medium-export’ folder which we unzipped in the previous step to our Jekyll project folder. Note that ‘posts’ and ‘_posts’ folders are different folders. ‘posts’ is the one containing our Medium exported blogs and ‘_posts’ is the one used by Jekyll internally.

Note: Medium considers comments/responses as posts so the posts folder will contain the comments/responses made in the original Medium article as separate html files. Since we don’t want to display them in our blog as separate entry, we can go ahead and delete them.

3. Import Medium articles to Jekyll

Jekyll reads posts from ‘_posts’ folder which currently contains sample posts.

NOTE: Jekyll project requires our posts in “markdown” format and the articles exported from Medium are in “html” format. The images used in our Medium blogs also need to be saved it locally along with Jekyll Front Matter.

This is a complex process and can be automated by single line of command of Python script.

Go ahead and clone the Python script from here (in the current project folder).

(In case you are using MacOS, Ubuntu or Debian, Python might already be installed on your system. If not, you can download Python from here. )

If you followed our directory structure, you should have ‘posts’ folder containing all the Medium exported articles and ‘medium-to-jekyll’ folder containing our Python script all inside the ‘beautiful-jekyll’ project. Now go inside the ‘medium-to-jekyll’ folder and execute these commands.

Here,  --source flag is the directory of the Medium exported ‘posts’ folder and  -- dest flag is the root directory of our Jekyll project.

Refresh the page at http://localhost:4000, to see all the Medium articles.

Note: If you don’t see the new posts, stop the Jekyll server and restart it again using bundle exec jekyll serve command.

The ‘posts’ folder containing Medium exported articles and ‘medium-to-jekyll’ folders are no longer needed. You may move them separate directory outside our Jekyll project or delete them.

4. Integrate Netlify CMS

So far, Medium articles are successfully exported and displayed. Next, we need to add the ability to compose, update or delete blog posts from the self-hosted project, with Netlify CMS. Netlify CMS allows to manage articles directly to Github repo. To support this, we need to create a new repository for the blog.

Create a new Github repository from here. You can name the repository as <github-username>.github.io. This will allow site to be hosted via Github Pages.

Note: Before you upload the project to Github, you might want to update the site’s _config.yml file. It currently contains dummy information and you will want to replace it with your information before uploading it. You can make other changes too as you may feel necessary. Find more details on Jekyll config file here.

Initialize git in the folder and upload it to the newly created repository.

After it’s done, give it a couple of minutes for Github pages to deploy your app and you should see the blog up and running at https://<github-username>.github.io if you are using Github pages. In my case, the site is available at https://sumeetbajra.github.io

Creating Github OAuth app

Now since the Github repository is ready, let’s integrate Netlify CMS. User authentication is based on Github OAuth for which we need to create a new Github OAuth app. Head over to Settings page or you can directly click here https://github.com/settings/developers

Click on “New OAuth App” and fill up the form. For ‘Authorization callback URL’, use “https://api.netlify.com/auth/done”

You will then get redirected to the OAuth app’s page which contains ClientID and Secret. You will need this later.

Creating Netlify app

Go to https://app.netlify.com and login with your Github account. Once logged in, click on ‘New Site from Git’ and select Github.

Here, if you wish to host your Jekyll blog using Netlify too, you need to select the newly created blog repository. Otherwise you are free to select any repository you want. Even an empty repository like this will work which I created for this example. In the next step, leave all the settings as it is and click ‘Deploy site’.

If you are not hosting the Jekyll project on Netlify, keep ‘Build command’ and ‘Publish directory’ empty.

Now we need to connect our Netlify app to Github OAuth. Head over to the Settings page -->Access control --> OAuth

Click on Install provider and select Github as provider. Copy the Client ID and Secret from the Github OAuth app’s page and paste them here.

Next, go to Settings --> Domain Management, click on ‘Add custom domain’.

Add your domain name <github-username>.github.io and click ‘Verify’ and then click ‘Yes, add domain’ if prompted with new message.

Note your Netlify app’s name. In my case, it is ‘practical-shaw-b147f7’.

If you don’t want to create Netlify app and instead wish to use your own OAuth server, you can use ‘netlify-cms-oauth-provider’ package. The detailed instructions are given in its Github page. You need to replace ‘https://api.netlify.com/auth/done’ in the Github OAuth app settings with your own server callback url in this case.

-–

Now let’s go back to our project. We need to create a new folder inside our blog called ‘admin’. Inside it, create two files namely ‘index.html’ and ‘config.yml’. This ‘config.yml’ file is different from ‘_config.yml’ file that is in the root folder. The content for each file is provided below.

In the config.yml file, replace ‘repo’ with your Github repo and ‘site_domain’ with your Netlify app’s domain <your-netlify-app-name>.netlify.com (skip this in case of custom OAuth).

If you want to know more about what each attribute in the config.yml file does you can check it out here.

Save the changes and then push them to Github. We are done now. If you head over to https://&lt;github-username&gt;.github.io/admin, you should see Netlify CMS’s login page like this.

Note: It might take couple of minutes for Github pages to update.

Go ahead and login with your Github account and you will be redirected to the CMS’s dashboard which contains all your posts. You can manage your blog posts from here.

Using Custom domain name (Optional)

If you wish to use custom domain, you can either

1. Host the site in Netlify (which I mentioned briefly above under ‘Creating Netlify app’) and set your custom domain as primary domain in Netlify dashboard’s Domain management. Then simply log in to the account you have with your DNS provider, and add a CNAME record pointing to <netlify-app-name>.netlify.com.
2. Continue hosting the site in Github pages and add CNAME record pointing to <github-username>.github.io with your DNS provider.

Obviously, these are just in regards to this tutorial. You have the flexibility to customize the project as much as you want and host them wherever you prefer to.

Want to learn more about Botsplash platform? Write to us here.