I wrote earlier today about updating this blog’s design in the process of switching from Octopress to Pelican to generate the site. As I said then, the move shouldn’t be construed as falling out of love with Octopress. I have a terrible problem with tinkering, and if a new framework or static site generator turns up, I often check it out. If it turns out to be good, that has a tendency to turn into many weekends and evenings spent wrangling HTML and CSS and other bits of code to build my site with the new tool. So it was with Pelican.

It started when I read an article by Gabe Weatherhead on Macdrifter, in which he described updating to the latest version Pelican. I was intrigued, particularly by the part where he explained that his webserver could render the site — all 1800 pages — in about 30 seconds. I had been getting irked (in a minor way) by the fact that Jekyll (which handles site generation for Octopress) was taking more than 7 minutes to generate my site which had about 1480 articles. Even taking into account the fact that his webserver probably has a much faster processor (and probably more RAM) than my aging iMac, that was quite an improvement.

Trying out Pelican

Since I was learning Python anyway and had a nice working virtual environment set up, I thought I might as well download it and play with it a bit. To test the speed, I set up the configuration file, used one of the default themes, and copied over the Markdown format article files from my Octopress installation. I have to say at this point that moving to a static blog generator based on Markdown-formatted files was probably the smartest thing I’ve done in a long time. If you want to move to a new system, you don’t have to wrangle with MySQL queries or anything else gruesome: in most cases, you just have to do a search and replace to tweak the metadata at the top of each file. Pelican uses a similar metadata format to Octopress, but it’s not enclosed in a YAML block, and there are other minor differences in terminology. However, that was very easy to fix by constructing a quick Text Factory¹ in BBEdit and working out what changes I needed to make. I fired up the generation script and amazingly it worked perfectly. Even better, generating all 1480 articles and one page (the ‘About’ page) took only about 30 seconds.

Now, I’m not obsessed with speed, I’m really not. I generate the files locally then rsync them up to my server, and I don’t even write that often so it’s not a wait I have to endure very often. It’s just that it’s some kind of unwritten rule of publishing that while I preview the single generated file I’m working on by using Octopress’ isolate feature, I only spot the typos and errors when I have generated the entire site (waiting 7 minutes in the process), only to have to fix the errors and wait all over again. Since my time for writing is crammed in little bits of time at evenings and weekends, this is a bit more of a chore than it needs to be. I don’t know if Jekyll is that slow for everyone with a similarly sized site, or if there’s just something weird about my configuration, but either way, Pelican was a lot faster given exactly the same content and structure.

Site structure

Pelican allows you to specify the URI structure and the location to save the files separately, which lets you tailor the structure of your site precisely. This made it easy for me to replicate the same URI structure that I use for my existing site. For example, this tells Pelican to use the URI archives/my-post-title/ for each article, which is enabled by creating a my-post-title folder within archives and then putting the content in an index.html file within that:

ARTICLE_URL = 'archives/{slug}/'
ARTICLE_SAVE_AS = 'archives/{slug}/index.html'

By default, Pelican looks for a slug: my-post-title metadata line in the article file, but I didn’t have that in my original Octopress files. That actually wasn’t a problem, because you can also tell Pelican to parse the filename for metadata like so:

FILENAME_METADATA = '(?P<date>\d{4}-\d{2}-\d{2})-(?P<slug>.*)'

That extracted both the date (which I had in the metadata anyway) and slug from my files and enabled the site to function while I was testing. However, I decided that it might be good to have a belt-and-braces approach and so once I was happy with the site, I wrote a quick and dirty Python script to capture the slug from each filename and insert the correct metadata line at the top of the file:

Another slight tweak I had to make was that — by default — Pelican generates author and category pages alongside the more usual stuff. Since I am the only author on this blog and don’t use categories, this was redundant. I could have just let it generate the files and either deleted them from the output or ignored them, but I suspected that I could fix it. It doesn’t seem to be documented, but you can turn those features off by setting the _URL and _SAVE_AS strings for each to empty strings:

AUTHOR_URL = ''
AUTHOR_SAVE_AS = ''
CATEGORY_URL = ''
CATEGORY_SAVE_AS = ''

You might remember that earlier in this article I wrote that Gabe Weatherhead was generating his site on his webserver. As he says, that’s not the usual way to do it, but the fact that Pelican is so fast actually makes it possible to set up a cron job to generate the site every 5 or 10 minutes. This means that if you can send a text file to your content directory on your server from any device (perhaps via Dropbox by using Mover.io), your new article will appear on your site when it is re-generated in a few minutes. That’s pretty cool, and opens up all sorts of possibilities for posting from mobile devices. I’m not doing that at the moment, and may never do so, but it’s great to have the option.

Design

After a bit of testing, I decided that I would make the switch, and use it as an opportunity to update the style of the site and clean up a few things that I hadn’t got around to sorting out. One of the very nice things about Pelican is that each theme contains both the templates to lay out the pages and the CSS, Javascripts, images and so on, and is completely self contained. If you have a number of themes on your computer, you can switch theme by altering one line in the configuration file:

THEME = "theme-name"

That’s really convenient, and means that when Pelican itself gets updated, the most you should have to do is perhaps alter some updated variable names in the theme to get it to work perfectly. However, unlike with Octopress, the default themes, while attractive enough, didn’t appeal to me enormously. I started off trying to modify the theme that was closest to what I wanted, but after spending hours on it, I managed to get myself into a terrible tangle trying to make the design responsive (that is, changing layout and size appropriately for different size screens). I am, it has to be said, a complete numpty with CSS, and found myself at many points yelling at the screen “Why won’t you text-align: right;!”, before realising that I had applied text-align: left; somewhere earlier in the cascade and forgotten about it. I’m not too bad with the basic stuff, but laying out elements on the page really baffles me, and it’s a painful process of trying something small, seeing what it looks like, trying something else, and so on. I write my CSS in Less or SASS because I find that the syntax makes it easier for me to grasp the hierarchy, but that can only get you so far when you don’t really know what you’re doing.

Thankfully, at that point, I found Skeleton. It’s a grid-based boilerplate suite designed to implement proper responsive designs, and it is quite lightweight so that you can use it just for the structure and basic stuff and then build your theme on top of it. Using Skeleton turned out to be a great move, and I could have saved myself an enormous amount of time by just using it from the start. I started from scratch and produced something that I thought was clean, readable and functional, but also scaled well to different screen sizes. You can try it if you like: gradually make your browser window smaller and you should see it go from a two column layout to a one column layout and the navigation links go from vertical to horizontal and images only. I don’t think I could ever have achieved that on my own, but Skeleton handles the basic stuff, leaving you just to tweak specific elements as needed.

Icons

In the re-design, I moved to a much simpler look, but I wanted to provide a bit more visual interest and make the various links in the menu and in the footer of the page (to my accounts on various social media sites and so on) more visually-distinctive. After a bit of a search on icon fonts², I came across Icomoon. This is a terrific site/service that provides nicely-designed icon packs (both free and paid-for options), and a free webapp that lets you select the icons you want and build your own custom font. It also has very clear instructions on how to use them, and I found it very easy to get it all set up. Frankly, it’s all a lot easier than using images for icons.

Wrapping up

I have to say that I’m really impressed with Pelican: it’s fast, it’s very configurable and it seems to be designed so that you can easily and cleanly alter and update the way that the site is structured.

I’ll still probably tinker a bit with the design, but I’m happy with the way it looks now. I still don’t have a clue about proper typographical spacing, so I think I could do with tweaking something about the spacing or line-height for the text, but I have no idea what or in which direction. If anyone knows of any basic guides to good web typographical principals I would be very grateful.