electronut Programming & Embedded Systems - by Mahesh Venkitachalam

Goodbye WordPress, Hello Jekyll.

Static Pages

I got introduced to web pages in 1995 when I joined Penn State University as a grad student. Those were the days of HTML and static web pages. Or cgi-bin if you were more advanced. Over the next 10 years, I built and maintained several personal web pages - mainly on 3D graphics programming and photography. By then, blogging had caught on, and eventually I created a page on Blogger as well - this time on electronics. That’s when I heard about WordPress.

The WordPress Experience

I was very excited when I first started using WordPress. Themes, Comments, User Registrations, Tag Clouds, Search, and Plugins for everything you could think of. What more could one ask? I spent hours and hours searching for the perfect theme, constantly fiddling with the settings. I also learned how to modify the WordPress PHP, CSS and other configuration files to tweak my site. I was initially using the built-in Rich Text editor, but switched to writing directly HTML for more control. Despite that, composing a post (Edit-Preview-Edit) remained a clunky process. I even tried some editors like MarsEdit which let you edit offline and upload, but I somehow could not create a good workflow.

Then, one morning I woke up to find that my website looked completely different. I had been hacked. I called the ISP, and was told it was not that uncommon with WordPress. They asked me to delete the WordPress installation and use a stronger password next time. I reinstalled WordPress, but I did not have a database backup. Luckily I did not have too much content up (Remember, I was busy fiddling with themes.) so I could recreate the site without too much effort. First thing I did is to install a database backup plugin that would email me a weekly backup. I then read up on WordPress security - there were plugins for that as well. Some of them warned that enabling certain options would lock out the administrator. Perfect- a room without a door. I also installed a Google Authenticator plugin, and used the app on my iPhone to get a code each time to log in. I felt like James Bond. Actually a tired James Bond. After a few weeks I uninstalled it.

Each time I logged in to WordPress, I was prompted to upgrade something or the other. WordPress security updates, plugin updates, theme updates - there was no end to it. I toyed with the notion of setting up a small store attached to my blog. And of course, WordPress had plugins for that as well. So I installed one, enabled user registration, and boom! Millions of Sales? No, a whole bunch of spam user registrations. But there were plugins to prevent those too. I backed out of the store idea.

About a year ago, I noticed that google search was flagging my site pages as compromised. I couldn’t see anything visually wrong with my pages. But looking at the HTML source, I found a few lines of suspicious looking code. I don’t know where that came from. Another round of WordPress re-installation. How fabulous.

My site consists of articles on programming and electronics - posts consisting of some text, code, a handful of images, and links to videos. Nothing too fancy. But the pages took for ever to load. To find out why, I installed a plugin performance analyzer, which was also a …plugin. It showed that the bulk of the time was taken up by WordPress’s own JetPack plugin. I turned off most plugins, till the analyzer showed that most of the loading time was for the analyzer itself. But at the end of the exercise, my site still remained slow.

I could go on and on. It’s too tiring to even think about it. I don’t have a hugely popular blog. But I value the few comments I get from my readers, and enjoy helping people out with their projects. But WordPress was just too painful as a blogging platform. It was taking away most of the joy of creating new content. Surely, there was a better way?

I had read a few articles on people moving to CMS free websites. One name that kept popping up was Jekyll. On reading up, I felt that Jekyll had the following advantages over WordPress:

  1. Faster loading. (No Database.)
  2. More secure. (No Database.)
  3. Easier to manage. (No plugins!)
  4. Simple, efficient workflow for posts.
  5. No more constant upgrading. Even if Jekyll becomes obsolete, the static pages I have generated will continue to work fine.

After sitting on the fence with this information for several months (Change is hard.), I finally decided to make the jump.

Switching to Jekyll

I’ve now switched to static web pages generated by Jekyll. Below are some useful links that might help you do the same. First, here is the mothership: the official Jekyll site.

The Process

If you are switching from WordPress, you really need to read these articles by Hadi Hariri and 8thcolor.com. They cover the whole process - Jekyll installation, WordPress data import, setting up Disqus for comments, etc. Also, early on in the process, unless you like the default Jekyll theme, take a look at jekyllthemes.org. I chose the Minimal Mistakes theme. It’s a good idea to read through any specific setup instructions in the theme documentation.


No transition happens without pain. Here are some issues I faced.

Jekyll Timestamps

Jekyll build works by re-creating your entire _site directory every time you run it. Unfortunately, it also changes the timestamp on every single file in the directory. This means you cannot use the timestamp as a criteria for intelligently deploying your site - by just uploading files that have changed since your last edit. If you try to use FTP tools that support directory synchronization, they will still upload the entire contents of the site, because the timestamps will all have changed. Fortunately there is a solution for this: use rsync with the file checksum as the difference criterion. You can read about this approach here.


When you export data from WordPress, it will get you all the pages and posts, but not your images and other media. You have retrieve the uploads directory yourself and manually change the links in your posts. If you are a sed expert, this should be easy. But I am not - so I had to do it manually, which was painful.


Some extras for your new Jekyll generated site:

MathJax Support

If you like math equations (Who doesn’t? \(e^{i\pi}+1=0\). Sorry.), you can enable MathJax on Jekyll by following this link. I put the MathJax JavaScript code in _include/_scripts.html.

Google Analytics

It’s easy to get statistics for your page visits and such. Create a Google Analytics account, get your tracking ID, and add the requisite code to your HTML. In my case, my theme already had the following code in _includes/_scripts.html.

{% if site.owner.google.analytics %}
<!-- Asynchronous Google Analytics snippet -->
  var _gaq = _gaq || [];
  var pluginUrl = 
  _gaq.push(['_require', 'inpage_linkid', pluginUrl]);
  _gaq.push(['_setAccount', '{{ site.owner.google.analytics }}']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
{% endif %}

So I just needed to set the analytics: variable in _config.yml to my Google tracker ID.

Adding a google search box to your Jekyll site is fairly easy. I added this code to _includes\_scripts.html:

<!-- Google Search Box -->
<script language="Javascript" type="text/javascript">
  function my_search_google()
    var query = document.getElementById("my-google-search").value;
    window.open("http://google.com/search?q=" + query
	+ "%20site:" + "http://electronut.in");

Then, I added the following code to _includes\_navigation.html:

<!-- google search -->
              <form style="display: inline;" onsubmit="my_search_google()" >
                <input style="width: 200px;" 
                       type="text" placeholder="Search" 

The above code is what shows the “Search” box on top of this site.


This is my first post after the switch. I am using Markdown for formatting this post, using my favorite editor emacs. As a developer, I have no problems using HTML directly, but I am really liking MarkDown because of the readability of the written text. Editing an HTML post once it’s written is painful. Here is my workflow for creating a post, on OS X:

  1. Create a new .md file in _post and edit using emacs.
  2. Change url in _config.yml to localhost.
  3. Issue a Jekyll build.
  4. Run Jekyll serve.
  5. Open localhost:4000 in a browser.
  6. As you edit, Jekyll will keep creating required files in _site. Reload the webpage to check your changes.
  7. When done, switch url in _config.yml to your actual website.
  8. Jekyll build.
  9. Run rsync with checksum to upload only files that really changed to server.
  10. Test post on website.

I find this workflow to be much more efficient and relaxing than the old way - waiting around for ever for my WordPress site to refresh after each edit.

For me, switching to Jekyll was a weekend’s work. My website loads so much faster now, that I am kicking myself for having not switched earlier. If you are tired of your buggy, slow, overflowing-with-spectacular-unwanted-features CMS, and long for the simplicity of good old static pages, go for Jekyll.

If you liked this article, please consider supporting my efforts by purchasing my book.

Python Playground, published by No Starch Press, USA, is a collection of imaginative programming projects that will inspire you to use Python to make art and music, build simulations of real-world phenomena, and interact with hardware like the Arduino and Raspberry Pi. Do check it out!