Moving Blogs to Pelican

12 min read · Posted on: Mar 17, 2013 · Print this page

Redesigning a site takes a lot of planning. I usually take it as an opportunity to study what is the state of the art and implement many long standing items from my wish list. So this post will be a lot more than explaining why I moved to Pelican from Jekyll.


I had stopped using Wordpress about two years back. I was a long time user of Wordpress and had even written some plugins. But I was afraid that whatever I had written was turning into a binary blob in some database.

Don’t believe me? Just open your Wordpress database tables in phpmyadmin or any other tool. If you use Microsoft Word, be prepared to get shocked seeing a lot of unnecessary tags like <SPAN>, class names like class=MsoNormal or converted punctuation marks like &lsquo;. Even web-based composers add a lot of horrible markup. I even tried using the plain text editor with Markdown markup. But something would still get mangled somehow.

Another major annoyance was that Wordpress had a huge attack surface. Everytime someone finds out a Wordpress exploit, your site is at risk. Only way to secure your content was to take frequent backups and keep updating the software. The latter was often painful as plugins tend to break in an upgrade. On top of all that, a little voice in the back of my head kept telling “Why do you a dynamically generated site for a blog when there is nothing inherently changing most of the time?”


Jekyll (and thousands of other static blog generators that followed) offered a simpler solution. Each blog post is stored as a file. Each time you make a change or add a new post, the entire site is “baked” and then uploaded. No need for your server to sweat about dynamically constructing your page for every hit. It is already composed. Just serve it. Simple and extremely efficient.

There were also some nice side effects. Text files could be version controlled. So there is always an option to go back in time and revert back to an older version of the site. Text files could also be easily searched manually or with simple UNIX tools. If you use Markdown or RST, your posts will be extremely readable without any silly markup.

The generated site was also much easier to understand. The site will no longer be littered with hundreds of files under scary directories like wp-admin or wp-include. I mean each of these are potential doorways for malicious exploits waiting to be discovered in the future. Jekyll sites are just made of plain old HTML, CSS or JavaScript. In other words, it is 100% content without any risky overheads.

Here is the best part - you can host your site anywhere! Think of the most basic hosting provider without PHP support (rare but possible), they should be able to serve HTML. Jekyll site can be browsed locally through its built-in server. Even with regular hosting, if ever your post gets too popular and gets reddited/slashdotted/DOS-ed, you can always just copy the site to a more available server and redirect gracefully.

So, what might sound like a luddite blogging tool is actually a much improved and fault tolerant system. Of course, it is not for the faint-hearted. I migrated to Jekyll in 2011.

So What was Wrong with Jekyll?

In short - Nothing. I was pretty much in love with the simplicity of it all. Until, like the cliche for ending relationships goes - I found out it was not Jekyll, it was me who had issues.

Slow Rebuilds

Of course, it is not without flaws. Jekyll takes an inordinate amount of time to ‘bake’ a site. Since it doesn’t support incremental builds, for every small edit to a post the entire site needs to be rebuilt. This is quite slow for even moderately big sites, often taking several minutes. Anecdotally speaking, when I tried python based tools, they seemed to be faster. But it could also be the effect of moving to my new SSD.


I realise that incrementally building or partial regeneration might be too hard or even impossible. After all, you will need to keep track of dependencies between your posts and parts of a page like sidebars. So we might be stuck with a full rebuild for a while and any speed improvements here would really enhance the blogging experience.

Ruby vs Python

Another pet peeve I had was that Jekyll was Ruby based. Even though Python was always my language of choice, I had intentionally picked Jekyll hoping to brush up my Ruby skills. I wrote Jekyll extensions. But I kept itching for Python.

I also tried to look for a single programming language platform for my blogging needs. As you might be aware Jekyll has several dependencies some of which are not Ruby-based like Pygments for syntax highlighting.

I tried to bucket all my preferred dependencies into the programming language they were built on and realised that installing both Ruby and Python would be inevitable:

  1. Uses Python - Pygments, Jinja
  2. Uses Ruby - Compass/Sass
  3. Either - Markdown

Of course, implementations have been ported between languages. But I prefer to use the original even if I need to maintain two platforms. I would rather work with a good implementation than a half-baked port.

Lack of maintenance

This has been addressed recently by the revival of Jekyll development by Parker. But Jekyll was neglected for a long time by the maintainers. Bugs and feature requests kept piling up. Of course, it is always a good idea to keep a blogging tool simple (looking at you, Wordpress). But issues like the site generation time were getting hard to ignore.

More options

This is not an issue with Jekyll as much as an acknowledgement of the competition. When Jekyll was introduced, it was new and cool in an almost retro sense. But then suddenly, everyone picked it up and it became obvious that it will be the new trend in blogging (and clearly, not retro anymore). This led to several hackers creating a static blog generator in a weekend.

In fact, it is not quite hard to implement 80% of what Jekyll does. But, as the saying goes, it is the remaining 20% that takes more than 80% of the effort. This led to a mind boggling number of choices for the geeky blogger - Nanoc, Hyde, Pelican, Poole, webby, hackyll and the list grows every weekend!

The good news is that now there are many options in my preferred language - Python. The bad news is that now there are so many options. So why did I finally choose Pelican? Before I tell you that let me engage/bore you with my new web design directions.

Forget Responsive Design, It is Mobile-first

When I started redesigning arunrocks in 2011, Responsive Design was a hot new trend in web design. People using mobile devices and tablets wanted a full-width experience without needing to use a separate mobile optimised version of the site. Responsive design (a poorly named term, according to me) promised to adapt the website’s layout to the user’s browser using CSS media queries.

It was fun to play with your site’s design and watch it magically transform on a mobile or tablet. But it was not entirely flawless. Early implementations of Responsive design implied that you would design for the big screen (desktops) and then adapt it to smaller screens. This was extremely wasteful. Big images and backgrounds meant for desktop users started flowing to the mobile users and, funnily enough, hidden from them too.

A better approach would have been to only load the minimum required resources first, especially for the mobile devices. The former is called Graceful Degradation and the latter is called Progressive Enhancement or in common language, Mobile First.

Mobile users are becoming more and more significant for a blogger. IDC predicts that by 2015, more people will access the Internet through a smartphone or tablet than a PC. Long form reading might not be easy or comfortable on a laptop or desktop screen. People would increasingly prefer to carry such reading material wherever they go, just like a book.

Of course, intuitively it is much more obvious since most people don’t carry their desktops to their bathrooms.


I am a big fan of Readability. If Web Design is 95% typography, then I would argue that Blogs are all about readability. If you have to design a good blog, then you must emphasise the reading comfort for the reader over any other design flourishes.

Readability can be significantly improved by making some objective improvements:

  1. Fonts - Select fonts optimised for on-screen reading
  2. Optimal Line Length - 50-60 characters per line
  3. High contrast - Text colour must contrast well against the background
  4. Negative space - Breathing space between lines, from the window edges

Of course, there is a lot more if you ask the experts - Vertical Rhythm, Leading, Hyphenation etc. But these are the basics, that I would expect every blog including mine to stick to.

Speed is Everything

My overriding priority with the redesign was to design for Speed particularly page loading speed. If a gradient could be done in CSS rather than images then do it. If an icon can be replaced by text, then do it. In other words, make it look simple and minimal. But that was just a side effect of making the page load faster.

Why is this so important? I hate sites that make you wait for its various pieces to load and come alive. It is 2013 and we still have sites that take several seconds to open especially on low bandwidth connections. Speed is crucial to the user experience. To me, speed is beautiful. I admire a snappy site.

Some of the key optimisations done to improve the speed of arunrocks:

  1. Maximum use of CSS3 - Even if some browsers don’t support it
  2. Replace Icons with Text - For navigation and other key interfaces
  3. Lesser Images - Avoid fancy backgrounds and logos, if possible
  4. Lesser Asides - Avoid extra sidebars, huge footers and other clutter
  5. Reduce Files - Avoid multiple CSS/JS. Remove JQuery and other redundant stuff
  6. Reduce File sizes - Minify and gzip almost everything

The book Hardboiled Web Design really influenced me while arriving at the first point. It encouraged me to leverage all the new CSS features even if all browsers may not support it yet. Style down rather than style up!

One of the fun things I do when I design a site is to obsess over the icon designs. Even though it is fun, it is usually pointless. Half of the users don’t understand what every icon means and studies have shown that it is usually the text what makes the meaning clear. So, text-only is usually better. Plus, Google Translate can help non-English visitors too.

In short, I aggressively cut-down anything that was non-essential to most visitors. I had some Jquery based functionality for keyboard navigation, social sharing, analytics etc. They were removed along with JQuery. Even CSS frameworks for mobile first patterns were dumped. Simple CSS rules were used instead. Sass helps in combining multiple CSS files and minifying them. Wherever a byte could be saved, it was saved.

Other Design Thoughts

This is my first site where I have made extensive use of Compass/Sass. It is a real time-saver compared to working directly on CSS. It helps you give a uniform look to the site. For instance by assigning link color to one variable, you can use color functions to assign that color’s shades to other elements. It can reduce typing while adding Vendor-specific properties in CSS.

The responsive design is now based on the needs of the design, rather than on known device sizes. Almost nothing had to be “hidden” in smaller screens, thanks to the Mobile First approach.

Upon completing the design, there was an overwhelming feeling of “this is a site I want to read”. Building something for one self is often the best approach to build something creatively. Not to mention that the satisfaction is immense too.

Blogging with Pelican

While choosing a blogging engine built using Python, Pelican seemed to be the most mature and actively developed project. Pelican is currently at version 3.1.1 and seems to have incorporated a lot of good ideas. Rather than list down all its features, I will mention some of the features that appealed to me:

  1. Ability to add extensions - Pretty obvious advantage
  2. Blog-aware - Supports tags, feeds and pagination
  3. Based on Jinja - familiar syntax to Django developers
  4. Supports Markdown extensions - Created a pullquote extension for myself
  5. Asset management with webassets - Supports Less, Sass, Coffeescript etc

Migrating posts from Jekyll to Pelican was not quite easy since they use different post structure (YAML versus meta tags) and directory layouts. Unlike Jekyll, if you have a file say favicon.ico in the top level directory, Pelican will not automatically copy it to the destination.

In Pelican, you need to mention such files in the configuration file explicitly. I did not like this initially, but later realised that it might be good from a security perspective.

The url structure is also more rigid in Pelican. All static content like CSS and images go to the /static/ folder. The pages (non-blog posts) go to a /pages/ folder (by default). I had to add specific rewrite rules using an .htaccess file to paper over such differences.

I also simplified the blog URL structure. It was a carryover from my Wordpress days. A typical blog title used to be:

Now it is just:

Shorter URLs are better for Twitter users and SEO. It is also easier to pronounce!

Markdown extensions

Python’s implementation of Markdown has a great Extensions API with several great extensions. For example, Header ID automatically creates a short id for each heading in the article, acting as anchor targets. This means that you can deep link to a content within a post. I wish Google could do this automatically when I am looking for a search string within a page.

I also wrote a pull quote extension which takes a phrase from the article and displays it in a bigger font beside the article. This usually helps while scanning long articles. A technique borrowed from magazine articles. (UPDATE: it has been open sourced! )

It is a Wrap

The wish list always keeps growing. There will be always something cool happening in the blogging or web design world. You cannot always keep up. But so far, Pelican gives a fast and easy to manage setup for my blogging needs. I would definitely recommend that you try it out too.

Arun Ravindran profile pic

Arun Ravindran

Arun is the author of "Django Design Patterns and Best Practices". Works as a Product Manager at Google. Avid open source enthusiast. Keen on Python. Loves to help people learn technology. Find out more about Arun on the about page.

Don't miss any future posts!

Comments →

Next: ▶   Easy and Practical Web scraping in Python

Prev: ◀   Treeify - Converting Tree Data Structures

Up: ▲   Blog

Featured Posts

Frequent Tags

banner ad for Django book


powered by Disqus