In my opinion, this course is more about about fabrication than building websites. As someone who is more familiar with tools for making web development easier, I’d like to share my strategy for building and maintaining my website.

The first thing to realize is that the class requires a website of static files to be served directly from the repository, as there is a lot of potential harm from allowing everyone to run server-side scripts. Hence, we must all upload regular HTML files. Moreover, these files must link to each other to create a coherent site. So, you have a choice: you can either write these files manually, or use something else to do the hard work for you.

Now, don’t get me wrong - this class is all about learning how to re-invent the wheel. But perhaps not for building websites. There are many technologies for building good-looking websites that make use of dynamic data (Meteor being my favorite), and making them scalable despite writing tons of code, and we’re not really competing with that here. So we’re really looking for the a basic tool that makes it easy to manage a static website for the class.

I ended up choosing Jekyll for this, as I’ve seen many other people use it and it has a pretty simple format for writing a website (Markdown), which is automatically converted to HTML. It uses a templating system to generate parts of pages so that they all look consistent - much better than copy-and-paste.

To get started with Jekyll, you’ll first have to install Ruby on your system: installation instructions. This also installs RubyGems, the package manager for Ruby. Jekyll is written in Ruby, and RubyGems installs Jekyll while your site is processed with Ruby code.

Now, you’re ready to get started with installing Jekyll. As noted on their website, it’s only a few simple commands:

~ $ gem install jekyll                      # Install Jekyll
~ $ jekyll new my-awesome-site              # Create a new Jekyll site
~ $ cd my-awesome-site                      # Go to the site directory
~/my-awesome-site $ jekyll serve --watch    # Start the Jekyll development server

The last command – jekyll serve --watch – is particularly cool because it basically shows your website on your local computer as you write it. It also watches files and automatically rebuilds them when it detects changes. So you can just save your file, hit refresh in your browser, and see your new site.

A Jekyll project is designed for a blog by default, and has a pretty standard layout. Files or folders that being begin with _ are special or ignored. All other files are included at their respective paths. I discovered that the easiest way to organize my weekly posts was to make a post file, and put the images in a corresponding folder. Here’s the layout:

layout

At the top of each post, you can include some basic parameters that help generate the site. For example, this post begins with

---
layout: post
title:  "Week 0.5: Create a Personal Blog"
permalink: /week0.5/
---

In my opinion, this course is more about about fabrication than building websites.

The permalink option makes sure the page appears at /week0.5. More importantly, any images that I link to from this post will use a relative path of week0.5/. Writing in Markdown is very simple as it’s very close to plain text.

Once I’m happy with my site, it’s a simple matter of using the following command to generate the HTML for upload:

~/my-awesome-site $ jekyll build -d ~/863.14/people/andrew_mao

where the final argument above is the location of my directory in the class archive. I can then do a quick commit and have a full site running on the server.

If anything is confusing above, you can use my site as a template. View the source code (with revisions) for this entire site. Specifically, check out _config.yml for settings specific for deploying to your directory on the CBA server.