edave.net

Converting a Wordpress blog to Jekyll and Twitter Bootstrap

By Dave Elkan

This is how I converted my long neglected blog from a Wordpress using some random theme to one powered by Jeykll using Twitter Bootstrap.

Tools you’ll need (and I assume you have installed)

Steps

  1. Install Jekyll, Jekyll import and Compass
   gem install jekyll jekyll-import compass
  1. Install Grunt, bower, Yeoman and the Yeoman Jekyll generator if you don’t already have them.
   npm install -g grunt-cli
   npm install -g grunt
   npm install -g bower
   npm install -g yo
   npm install -g generator-jekyllrb
  1. Bootstrap your jekyll site with yeoman
   mkdir your-site-name
   cd your-site-name
   yo jekyllrb

Follow the prompts to configure your website as you see fit.

This process assumes you use the Compass sass compiler, the Redcarpet markdown compiler and use the default Jekyll site template.

If you’re using a git based deployment (i.e. Github Pages or Heroku) you may be interested in enabling grunt-build-control.

  1. Export wordpress backup file

Name the xml file wordpress.xml and place it in the app directory created in step 3.

  1. Import wordpress backup with jekyll

From the same directory as in step 4 run:

   ruby -rubygems -e 'require "jekyll-import"; JekyllImport::Importers::WordpressDotCom.run()'

This will place a markdown file for each wordpress post in your _posts directory.

  1. Re-format HTML to Markdown.

    Unfortunately Jekyll-import does not convert the HTML from your wordpress website into Markdown. I wrote a simple nodejs module to help convert the HTML posts to Markdown.

    Install jekyll-html-md

    npm install -g jekyll-html-md

    From the app directory of your jekyll website created in step 3, run the following command.

    jekyll-html-md

    With any luck it will convert your HTML posts to Markdown, leaving a backup of the HTML files in _posts_html. You can delete this directory when you’re satisified the conversion was successful. If it breaks, hit me up on Twitter @edave

  2. Ensure your URLs are the same as before.

If after migrating your blog will have the same URL (i.e. it’s not a Wordress.com blog) you will want to ensure the URLs to your posts remain the same. For me that was just a matter of removing the :categories portion from the permalink config setting in _config.yml. This will depend on which URL format you used in Wordpress.

My final config looks like:

   permalink: /:year/:month/:day/:title
  1. Copy over any images

If you uploaded any images to your wordpress blog, you’ll need to copy them over.

For this I simply copied all of the files located in wp-content/uploads to the img directory in the app directory. I then did a bulk replace on any absolute paths in my posts to match this new location.

  1. Install Twitter Bootstrap using bower
   bower install sass-bootstrap --save

To import Bootstrap into your css, add the following line to the top of main.scss in the _scss directory.

   @import "../_bower_components/sass-bootstrap/lib/bootstrap";
  1. The dev loop

The yeoman jekyll generator comes with a decent dev loop. To work on your website, from the root of the directoy you created in step 3, run the following command.

   grunt serve

This will run a small web server locally on port 8000 and open it in your browser automatically. When a change is detected the site will be regenerated and the website will be refreshed.

  1. Get hacking

Do whatever it takes to get your website looking great!

  1. Publishing your website

To publish your website you’ll need to build it:

   grunt build

Subsequently you can use grunt deploy if you chose to set up grunt-build-control.

Personally I use grunt-rsync.

Good luck!

Please let me know on Twitter @edave if a step doesn’t work. I no doubt missed something.

comments powered by Disqus