Week 1: Principles, Practices and Project Management

This Week's Assignment

The assignment for this week is split into two parts:

  1. Build a personal site in the class archive to track my progress through the Fab Academy
  2. Document some potential final projects

This post is about how I went about designing this website. My ideas for a potential final project can be found in the Final Project Proposal post.

Building a Website

I've not done any web development since I was in high school, coding in raw HTML in notepad, so I had to do quite a bit of research and experimenting to bring myself up to speed.

Based on the limitations imposed by the Fab Academy archive (static files only, no database, PHP etc.) I decided that I would try and use a static site generator. There were a lot to choose from. In the end I narrowed my selection down to two:

  1. Octopress: Described as "A blogging framework for hackers". It's a static site generator based on Jekyll and uses Ruby.
  2. Pelican: A static site generator based on Python.

My main reason for going down the static site generator route was that I can focus on content, leaving a lot of the HTML, CSS and JavaScript production "behind-the-scenes".

I decided to give Octopress a try first, as it looked to be the more popular option.

Trying Octopress

A blogging framework for hackers

Sounds just like what I was looking for! Here's the thing - I tried setting Octopress up on three different machines, on both Windows and Linux Mint, and had a different set of problems for every install. It was a nightmare. While I do most of my development on Windows, I do jump into Linux sometimes so I wanted a workflow that would work happily across both platforms. On top of that, not being able to get through a "Getting Started" style tutorial without errors, not once but THREE times, is usually a sign to move onto something else.

Most of the install problems revolved around getting Ruby installed and working correctly. Never having looked at a line of Ruby in my life also wasn't going to help if I did find I had to jump into the source to change something to work how I wanted it.

Trying Pelican

Pelican was next for evaluation, and thankfully it went a lot better. For starters, I've managed to install it on all three of my computers, in both Windows and Linux Mint. I'm also "conversational" in Python, so having an engine written in a language I can make changes in is a big plus.

Having got a basic site up and running without any issue, I started looking at customisation for my Fab Academy site. Theming in Pelican is pretty easy - just grab the theme and point to its location in your pelicanconf.py file. Mobile devices were something I never had to consider back when I was using raw HTML in high school, but I think making a site today that isn't mobile compatible is pretty lazy. Bootstrap seemed like it was just what I needed, and there was already a Pelican theme based on Bootstrap3: pelican-bootstrap3 by Daan Debie.

I'm still working on customising the theme to really get what I want, but it has a lot of really cool feature built in that should "just work". For example:

  • My posts should have a comments section using Disqus (They work in my local serve of the website. If they work on the Fab Archive will be another matter!).
  • I've got buttons for various social networks so that people can +1, Like and Tweet my articles in one click. It's all done through a service called AddThis.

Some of the features I'm looking to add are:

  • Google Analytics, so that I can keep a track of who (if anyone!) is looking at my site. This should be pretty easy to setup, as the pelican-bootstrap3 theme already has support built it.
  • A better navigation menu. I think a navigation menu that sits to the left of the main content works well for Fab Academy style sites, and I would have it collapse to the top for narrow (i.e. mobile) devices. Getting this up and running is involving a bit more customisation of the theme than I can manage this week.

I'll likely continue to make improvements to the site as the weeks go on. I've only just scratched the surface of web development but I'm really starting to enjoy it. Once I get more familiar with the "how" I can focus on the really hard bit: good design.

Site Source

All of the source for this site is in my BitBucket. Because I forked the pelican-bootstrap3 theme to make my own custom version, pelican-bootstrap-fabacademy, it's hosted on my GitHub. I've managed to embed the theme on GitHub inside the Mercurial repo for the site. Probably a terrible idea, but it seems to work quite nicely.

So, Is A Static Site Generator Worth It?

In short, no.

As with most things in life, xkcd explains it better than I can:

xkcd: Automating xkcd: Is It Worth The Time?

Don't get me wrong, static site generators are great, and I especially like Pelican. The main problem is that they are all pretty much geared up for blog-style websites and that's not a format I think works well for a Fab Academy site. The best Fab Academy sites I've seen all have a pretty basic structure:

  1. An "About Me" page
  2. A section for weekly classes.
  3. A section for the final project.

Most importantly, Fab Academy sites have finite content. Let me clarify that: Fab Academy sites have a set number of pages and are only active for a couple of months. This isn't a blog I'll be writing forever and ever. In order to get the structure I wanted, I've basically been taking a hammer to the theme and content templates. And it's still not there. I would have been a lot quicker just setting up some basic temples to make a skeleton site and just filling in the content as I went.

Ah well. Live and learn. That's pretty much what this whole process is about anyway!

Now the real test: leave a comment, if they're working :P

Update! 2015-02-05

So comments worked fine (yay!), but none of my links to internal content worked in the version I had on the Fab Academy archive (I have a test version hosted on my GitHub). The problem was that on Windows, I couldn’t use the {filename}/path/to/content syntax to link to internal content like images and other pages. Pelican just complained that it couldn't find the files and didn't update the URL.

The result was that the absolute links I used instead worked fine on a local serve and on my GitHub because my site lived at the domain root i.e. it was at http://icchalmers.github.io/ and not a level down such as http://icchalmers.github.io/blog. I had been assuming that having SITEURL = 'http://fabacademy.org/archives/2015/eu/students/chalmers.iain' would cause my “absolute” links to be absolute to SITEURL and not just to fabacademy.org. Oh well...

So for now, this site can only be reliably generated on *nix systems. My thanks to Avaris on the #Pelican IRC channel for his help. We might not have fixed the problem, but it's nice to know there are active developers willing to help. Maybe I'll find the time to try diving into the Pelican source to see if I can fix the problem. It's about time I tried my first ever pull request on an open source project...

Comments

comments powered by Disqus