The First Post

Fri 15 August 2014
tags: meta

This is the first post in the blog section of the website; huzzah! This thread will be about the website itself and how it works. I'll be making updates in the form of posts as and when I add features.

Overview

I set up this website mainly to present myself in a (semi) professional manner, and also to learn a bit about web programming. Although I have messed around a bit with Flask, a server-side web framework for Python, I've never actually written a website end to end. The fact that this is a learning excercise for me is important, and motivated my decision to build a static website rather than go for a canned solution in the form of Wordpress or Drupal. While I can certainly see the utility of such tools, if had have used one then I would rather have missed the point of the whole excercise.

Static pages

A fully dynamic website seems to me to be overkill for what I have in mind. Essentially I'll be creating some content and posting it, as well as editing some other static pages. There is absolutely no need for pages to be dynamically created server-side every time someone requests a page. Although the slowdown will probably be negligible due to cacheing , the increase in complexity is certainly not warranted. I would, however, like to avoid writing as much boilerplate as possible (especially HTML) as this is pretty cumbersome. It would seem to make sense if I were to write content using some simple markup language (such as ReStructured Text or Markdown) and then have all the boilerplate generated for me using scripts.

Site generators

It turns out (unsurprisingly) that I am not the first person to come up with this idea. Such tools are collectively known as "static site generators", and there are myriad examples. It seems that whenever someone has needed to generate a static website they have written their own damn site generator to go along with it. I debated a while about using such a site generator, but on reading the docs for Jekyll and Hyde I realized that even these lightweight tools were too heavy for what I really wanted to do. Part of the problem that I have is that never having built a website end to end, I don't really have a feel for how the different pieces interact. I am a great believer in learning by doing, and have no shame re-inventing the wheel when it will get me more understanding about a problem. I equally have no shame in later discarding my mishapen, decidedly square-looking wheel once I have understood why the next person's precision-crafted circular masterpiece is better. This website is my square wheel.

The current design
Backend

The website is made using a combination of Markdown for content, Yaml for configuration / metadata and Python code gluing it all together. HTML structure / boilerplate is marked up with the Jinja templating language and Python scripts load and populate the templates with the markdown content and the Yaml metadata. This general approach is used in the vast majority of static site generators that I saw.

Frontend

I also put a bit of thought into the "frontend" part of the website. As this is the part which people actually see it is necessarily more important for a static site (for a dynamic site or web service one could argue that function is at least equal to form in importance). I quickly established that if I were to write the css from scratch I would be working for a long time before I had something which looked decent. I decided to use the much-loved Bootstrap "frontend framework" to kickstart my design; It's much easier to iterate on something which already looks half decent. I have tried as much as possible to adhere to the Unobtrusive Javascript design principle. I use Javascript in my pages to do collapsable panels and to enable rendering of mathematics with MathJax, but have taken care to have the panels un-collapsed by default so that users with javascript disabled can still read the content.

Unfortunately it appears that NoScript blocks webfonts by default, which means that the FontAwesome icons next to the page titles will not render correctly. In order to combat this I should make a note of all the icons that I use and generate PNGs for use when webfonts are not available. Another thing to add to the to-do list!