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.

Pitfalls

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.

Images

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.

Extras

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 -->
<script>
  var _gaq = _gaq || [];
  var pluginUrl = 
 '//www.google-analytics.com/plugins/ga/inpage_linkid.js';
  _gaq.push(['_require', 'inpage_linkid', pluginUrl]);
  _gaq.push(['_setAccount', '{{ site.owner.google.analytics }}']);
  _gaq.push(['_trackPageview']);

  (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);
  })();
</script>
{% endif %}

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

Google Search

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:" + "https://electronut.in");
  }
</script>

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

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

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

Conclusion

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.