DEV Community


Migrated away from Wordpress

automationhacks profile image Gaurav Singh Originally published at on ใƒป7 min read

Wordpress to Jekyll

Attribution: Wordpress logo,Jekyll logo

Hi there ๐Ÿ˜„

Iโ€™ve recently moved the blog away from Wordpress and have dived into the wonderful word of staticsite generators using Jekyll and Github pages. This post talks about how the overall process lookedlike and what were some of the additional customizations I added along with references. Letโ€™s getstarted.


Why? You might ask, Well, Wordpress had been great for me initially. It enabled me to start bloggingwithout any consideration of the technical setup needed and it was quite easy to have a fullyfeatured blog within minutes

However over time, the overall experience felt a bit bloated and what i realized is that I do notreally make use of all the capability that Wordpress as a platform offered.

Also, For any new functionality that I might need, I had to add Wordpress plugins (and thatrequires a business plan at the least)

It conflicted with my goals of having a minimal, fast technical blog/portfolio site that I have fullcontrol over and customize to whatever needs might arise and this ultimately motivated me to takethe plunge and move away from Wordpress

Welcome to the world of static site generators (SSG)

I had been aware of static site generators before and had heard of Jekyll, Hugo, Sphinx amongmany others. Watched a few videos around this and ultimately found Jekyll to have the requiredfunctionality and customization for my needs

One of the motivating factors in favor of Jekyll was that it has a very tight integration withGithub, plus the hosting of the site is very graciously taken care of by Github. I had to onlybuy the domain on Namecheap and do setup and the site was good to go. ๐Ÿ™Œ

The icing on the top was that my entire workflow involves writing posts in plain markdown and thenusing Git and Github for the publishing workflow. Canโ€™t get more minimal than that. ๐Ÿ˜†

There were many good tutorials that other people had already put out for this process and that ireferred while migrating, check them out

Below are the steps that I took and my experience around it.

Download content from Wordpress and import into Jekyll

Depending on which platform your current blog is hosted on, there are different importers that youcould use to convert the dumps to a format that Jekyll can understand

My site was hosted on and so I had to download the content and then runJekyll import tool

Once done with above, It gave me a sample layout with all the images and other posts in _postsdirectory

Install ruby and gems

Jekyll docs are very well written and explain these in detail, Before starting ensure you have Ruby,RubyGems and other libs setup. Follow instructions fromJekyll Quickstart

Once done, Below are the steps to create a new Jekyll site

Create an empty Jekyll site with default minima theme

jekyll new <>

Note: You should have a repository with in GitHub already, You can eithercreate it first and then clone and then run above command or usegit remote add origin <your_repo_url> >Read more here

You can serve the newly created site on localhost, which you can access on port 4000.localhost:4000:

bundle exec jekyll serve

In Jekyll, posts are maintained in _posts directory and are ordered in yyyy-mm-dd-<title>format, You can also write drafts in _drafts folder and Jekyll is smart enough to not serve theseon your site until you are ready and move it under posts

If you want to view drafts in your local served Jekyll website

jekyll serve --draft

Push to GitHub and you are live

Once you push the site to Github it would take a couple of minutes for it to be setup

Setting up domain

You can go with the default domain ( or setup your own.

To setup your own domain, create a file CNAME in folder root and add your domain name

Modify Github settings

You also would need to add this domain in your repositories settings

Add this domain in Custom domain and also select Enforce HTTPS if your domain supports SSL. Readmore about how to do this onGithub docs

Update DNS provider

You can very easily buy a domain of whatever provider you want. I use namecheap for my site and youneed to setup A record in your Advanced DNS settings. Note the IP address of Github servers mighthave changed so figure out the latest ones and replace in your settings

Namecheap DNS config

Once the setting has been done in your Github repository and the domain provider. Wait for sometime for the setting to take effect. Usually a few hours but can take max of upto 24 hours

Letโ€™s start customizing with plugins

Jekyll uses Gems for most of the additional functionality that you mightneed and associated plugins, Below is the basic process for installing and adding any new Gem intothe site

Add below lines in _config.yml under group :jekyll_plugins do, Below are the ones that I haveinitially added and few of which I would explain in further sections or future blog posts

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-seo-tag", "~> 2.6"
  gem "jekyll-gist"

You can then install all the gems mentioned in Gemfile using below:

bundle install

Then, add these under plugins list in _config.yml

  - jekyll-feed
  - jekyll-paginate
  - jekyll-seo-tag
  - jekyll-gist
  - jekyll-twitter-plugin

Some manual fixes to be made

The export and import process leaves some cleanup activities to be done on the posts/pages, For alarge enough site you might want to automate some of these

Encoded Strings

  • You might see some encoded strings show up and might want to replace with character listed next:
&#8217; <single quote>

Get Github gists to render

  • Also if youโ€™ve been using Github gists for code samples, You might find these not rendered on thepage. To fix these, Find the html code blocks with data-gist and replace with below liquid tag,The cool thing here is that since its your own Github account, you only need to specify the UUID like ID for gists to be rendered
{% gist d366955370d58dc2ca40c185b62cd829 %}

Fix images

You can move all the images downloaded from Wordpress into an assets/images folder and then fixthe references in your posts/pages such that they are served from your repository

Some steps for the same can be:

  • Search for <figure> or <img> tag and replace it with markdown syntax of![image alt text](path_to_assets) or change the src attribute, You might have all the imagesin a wp-content folder and so the easiest thing is to move the entire folder underassets/images and then fix the references to these images
  • To be more specific, replace all image URLs beginning with /wp-content with/assets/images/wp-content

Optional updates

  • Search for <pre> tag and replace with code-block in order to get syntax highlighting usingJekyll rouge
  • If you are cross posting your blog on sites like or medium, then you might want toupdate the canonical_url so that your new blog site is thecanonical reference
  • Finally check local site if all looks good at before pushing to Github

Note: There would be lot of HTML mixed with markdown in the blog and while you can certainly fixthem into a markdown syntax, it would take a long time. I decided to let it be as long as theURLs/Images were fine


To setup comments on the blog, i chose, The process is quite simple and you need tocreate an account on Disqus and then make couple of changes into your _config.yml

# Disqus Comments
  # Leave shortname blank to disable comments site-wide.
  # Disable comments for any post by adding `comments: false` to that post's YAML Front Matter.
  shortname: <your_shortname>

This would start showing the Disqus comment block if your page has comments: true in the frontmatter

If you want to ensure that comments are enabled on all the pages then add below defaults to your_config.yml, this is sweet ๐Ÿ˜† because you donโ€™t need to repeat the same values in all theposts frontmatter.

  - scope:
      path: ""
      type: "posts"
      layout: "post"
      author: Gaurav
      comments: true

Psst ๐Ÿคซ: You might want to refer tothis blog for details

Setup Google analytics

You might want to hook up Google analytics or equivalent to get some idea on your audience. Createan account on Google analytics and that should give you a unique id. Update that in your config.ymlfile and you are good to go with basic analytics.

Obviously there are more customizations that can be done, but that would probably be a future post

# Google Analytics
google_analytics: <unique_id>

Psst: ๐Ÿคซ: Refer to this for more details


Voila, You have a fully customizable site up and running. I will be posting more about this in thefuture as I learn more about Jekyll.

If you found this post useful, Do share it with a friend or colleague. Until next time. Happycoding.


Here are some more resources that you can refer:

To learn more about Jekyll, Check outMike Danes videos on YouTube

Discussion (0)

Editor guide