New Website!

7 minute read

First off, welcome to my new site. Where my old site was a hand-made page and slightly crummy, this one is built on top of Jekyll and the Pixyll theme, and looks pretty good (at least to me).

For my new site, I wanted somewhere I could gather together all my work and put it on display (as the old site did), and also provide somewhere I could host any articles I felt like writing. I suppose the latter is blogging, but I will try to stay away from slice-of-life blogging, and concentrate on informative, probably technical posts: the kind of thing that’s useful for when I’m having a problem and I do a search for it, and someone else has already written up their encounter with the problem, and what they did to solve it.

Choosing a Starting Point

My “problem” for this article was that my existing site:

  1. Didn’t look very good. I’m not a designer, and it showed.
  2. Had a poor layout. Again, the design thing.
  3. Wasn’t terribly easy to maintain. Sure, writing HTML isn’t hard, but it does distract from the content a little.

I wanted something that could solve those issues, and be portable across hosting providers, be something I could host locally without to much trouble (to aid development), and which would work on static hosts like GitHub.

I’d previously read about Jekyll in GitHub’s blog, but it never really clicked with me. Still, I was hosting on GitHub, so I thought I’d check it out first.

The idea is that you write a simple proto-site, build the actual site from it using Jekyll, then deploy the site to your web host. If you’re hosting on GitHub, you can deploy your proto-site, and they’ll build it for you. I wanted to test my site out locally first though, which meant installing Jekyll.

Installing Jekyll & Theming

First of all, I created a new Git repository in my site folder. Version control makes life so much easier when trying new things.

I followed this guide for getting Jekyll set up on Windows, choosing Rouge instead of Pygments because the latter looked like a lot of bother to set up locally. Once Jekyll was installed, the only interaction I had with it was to run jekyll serve --watch from inside my site folder, which builds the site and starts a local web server for it at http://localhost:4000.

The basic theme is serviceable but doesn’t look great, so I Googled “Jekyll themes”, and decided on Pixyll. Installing it was just a matter of copying it into my site folder, letting it overwrite the existing files.

Customising The Site

Existing Content

I then had to customise my Jekyll + Pixyll site:

  1. I customised my /_config.yml to fill in the relevant information
  2. I deleted the example posts, the README.md and the custom domain file. I also deleted the contact form because I wanted to just put my email up for people to use directly.
  3. I customised the /about.md page to be about me instead of Pixyll.
  4. I tweaked the footer include at /_includes/footer.html to hold my copyright info.

New Content

I created a new branch in my repository for content being added to new files. The idea is that it should help keep what I create separate from what I got from Jekyll and Pixyll, and I can just merge the content branch in every so often. Time will tell if that strategy works out.

Anyway, posts go in the _posts folder. I also created an archive page to list all my posts, since that was missing from the Pixyll theme, and a “My Projects” subfolder for pages listing all my work. Everything is written in Markdown, except from the icon + text description for my applications, and the image and caption on my About page.

Because I didn’t want to make too many changes to the existing Pixyll files, I decided to put the CSS for the above HTML in a new /css/custom.css file, and I added the following to my /_includes/head.html:


<link rel="stylesheet" href="{{ "/css/custom.css" | prepend: site.baseurl }}" type="text/css">

The {{ }} brackets are Liquid syntax. Liquid is a preprocessor that Jekyll runs to substitute in variables and perform simple logic operations on content you write.

Anyway, with those pages written, I had to also update /_includes/navigation.html to add a link to my new projects page (which I did back in my main branch). A neater implementation would be to create a navigation list in my _config.yml, and rewrite the navigation page to generate a set of links for everything in the navigation list, but it wasn’t really necessary in my case. If you have a lot of non-post pages though, it would be of more benefit.

Styling Tweaks

Update: these changes have now been merged into Pixyll, so others can enjoy them without any extra effort!

Abbreviations

While I was converting some of my content to Markdown, I came across a little problem: I use Wrye *ash to refer to the set of Wrye Bash and related utilities, and xEdit to refer to TES4Edit and its related utilities. In HTML, I’d just wrap these in an <abbr> tag and give it a title, but I didn’t really want to put HTML in my Markdown (which you can do) unless I had to.

It turns out that Kramdown, the Markdown parser that Jekyll uses, extends the syntax to cover abbreviations, you just do the following:

Kramdown also supports GFM.

*[GFM]: GitHub Flavored Markdown

which gets turned into:

Kramdown also supports GFM.

This is pretty neat, but it turns out that Pixyll doesn’t have any styling for abbreviations by default, so it’s impossible to tell there’s hover-text unless by accident. To get the above styling, I added the following:

abbr {
    border-bottom: thin black dotted;
    cursor: help;
}
Heading Font Sizes

Another thing I noticed while writing the site was that Pixyll’s sizes for <h1>, <h2>, etc. elements was a bit… off. <h1>, <h2> and <h3> looked fine on their own, but the jump in size between them was weird and <h4> was identical to <h3>. I looked in the Pixyll repository issue tracker and found this issue, so I re-scaled the headings according to the ratios given in the first link in that issue. I had to increase the heading sizes on small screens slightly, but I think it still looks good.

I also wanted a simple, clear and unobtrusive way of linking people to my accounts on various social media sites, as well as a few other things such as the site RSS feed, my email and my PayPal donation button. I had a quick look for anything that already existed, but didn’t find anything that would fit with my theme, so I wrote my own.

First, I added some entries to my _config.yml:

twitter_username: OliverHamlet
github_username: Ortham
linkedin_username: oliverhamlet
paypal_url: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&amp;hosted_button_id=HDR3YBGGYCLBG
google_plus_id: 104661746805670028939

I then decided that I wanted to use the icons from Font Awesome to represent the various sites, so I added the following line to my /_templates/head.html:

<link href="//maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet">

I them created a new _templates/social_links.html file with the following content:


{% if site.github_username %}
<a class="fa fa-github" href="https://github.com/{{ site.github_username }}"></a>
{% endif %}
<a class="fa fa-rss" href="{{ "/feed.xml" | prepend: site.baseurl }}"></a>
{% if site.twitter_username %}
<a class="fa fa-twitter" href="https://twitter.com/{{ site.twitter_username }}"></a>
{% endif %}
{% if site.google_plus_id %}
<a class="fa fa-google-plus" href="https://plus.google.com/{{ site.google_plus_id }}/posts"></a>
{% endif %}
{% if site.email %}
<a class="fa fa-envelope" href="mailto:{{ site.email }}"></a>
{% endif %}
{% if site.linkedin_username %}
<a class="fa fa-linkedin" href="https://www.linkedin.com/in/{{ site.linkedin_username }}"></a>
{% endif %}
{% if site.paypal_url %}
<a class="fa fa-paypal" href="{{ site.paypal_url }}"></a>
{% endif %}

The Liquid expressions are there to make sure icons aren’t shown for any accounts you don’t specify.

I’ll probably split this little feature off into its own repository, and extend it to cover more sites, as it’s probably the sort of thing others would find useful.

Wrapping It All Up

After writing my content and applying my changes, all that was left to do was push my site to GitHub, which was as simple as always. A website is never finished, but I got an elegant, extensible one built in a day, and changes I can hopefully get pulled upstream.

At some point I’d like to add a “reading time” thing to posts, and an unobtrusive table of contents (maybe collapsible?) to longer posts, but there’s no hurry for them.

Updated: