ikewalker.github.io

Mechanics

Mechanics is our external facing engineering blog built on top of the Octopress blogging platform.

Set Up

=====

The version of Octopress we are using requires that ruby 1.9.2 be installed. If you haven’t already, please install RVM. If the next step fails at all it will be helpful if you also have Homebrew installed to easily install any missing dependencies that are required. Additionally, the biggest challenge most have faced is the lack of the correct gcc when trying to install a version of ruby on OS X. If you are running OS X 10.6 (Snow Leopard), make sure you have installed a version of XCode that is before 4.3. If you are running OS X 10.7 (Lion), then you need to ensure that you have installed the command line tools for XCode. You’ll need an Apple ID.

You will probably want to uninstall Xcode before installing the command line tools for Lion:

$ sudo /Developer/Library/uninstall-devtools --mode=all

Then install ruby 1.9.2 (this step may take some time):

rvm install 1.9.2

Then clone this project:

git clone git@github.com:flite/mechanics.git mechanics
cd mechanics
ruby --version # Should report Ruby 1.9.2

Next install dependencies:

cd mechanics
bundle install

Setup your copy to be able to deploy to Github Pages:

cd mechanics
rake setup_github_pages

This will:

If all goes well you should see the following message:

## Now you can deploy to http://flite.github.com/mechanics with `rake deploy` ##

Then pull to get the latest of our blog source:

git pull origin master
Already up-to-date.

If you run rake generate then rake preview you should be able to see the latest copy at localhost:4000.

You’re now ready to start posting and deploying (SEE BELOW FOR DEPLOYMENT INSTRUCTIONS).

Post Generation

=====

Octopress provides a rake task to create new blog posts with the right naming conventions and default yaml metadata.

rake new_post["title"]

new_post expects a naturally written title and strips out undesirable url characters when creating the filename. The default file extension for new posts is .markdown. This is configurable via the Rakefile (new_post_ext).

Example:
rake new_post["Zombie Ninjas Attack: A survivor's retrospective"]
# Creates source/_posts/2011-07-03-zombie-ninjas-attack-a-survivors-retrospective.markdown

The filename will determine your url. With the default permalink settings the url would be something like http://site.com/blog/2011/07/03/zombie-ninjas-attack-a-survivors-retrospective/index.html.

Open a post in a text editor and you’ll see a block of yaml front matter which tells Jekyll how to processes posts and pages.

---
layout: post
title: "Zombie Ninjas Attack: A survivor's retrospective"
date: 2011-07-03 5:59
comments: false
categories: [Category1]
author: Your Name
published: false
---

Here you may turn comments on or off and add categories to your post. We use a standard of always specifying categories via an array. You can leave the field empty or specify an empty array if you wish to leave your post uncategorized. But if you want to specify even one category put it in an array.

Additionally, you should add/replace author: Your Name with your name for proper attribution on a post. If you are working on a draft, you can add published: false to prevent it from being posted when you generate the site.

Multiple Category Example:
categories: [CSS3, Sass, Media Queries]
Formating

To test your formating, please refer to http://mechanics.flite.com/test for all the styles used on this site.

Generate & Preview

=====

rake generate   # Generates posts and pages into the public directory
rake watch      # Watches source/ and sass/ for changes and regenerates
rake preview    # Watches, and mounts a webserver at http://localhost:4000

The typical flow when developing a new post is to run rake generate which will create posts and pages in the public directory and then rake preview which will watch for changes and mount a webserver addressable at localhost:4000.

If you want to work on a post without publishing it, you can add published: false to the post’s YAML header. You can preview this post with rake preview on your local server but it won’t get published by rake deploy.

Using Pow

You can also use the Pow webserver like so:

cd ~/.pow  
ln -s /path/to/mechanics mechanics

Once setup with POW, you can just run rake watch and load up http://mechanics.dev instead. See the Pow documentation for more information.

Site Deploy

=====

When you’re done with your post and have verified via preview that things look the way you want make sure to commit your source changes and push them to origin master.

__NOTE: Ensure that you have the latest source from the mechanics master branch__.

The process of deploying with Octopress pushes the entire blog every time. As we add more post this will naturally get slower. According to online sources at worse this takes some with a large amount of posts upwards of 5-8 minutes.

To deploy, first generate the site, then deploy:

rake generate
rake deploy

This will generate a new site in your _deploy directory and then check that into the gh-pages branch of the mechanics project which is why you should ensure you have the latest from master to pick up any other blog posts or any UI changes.

Then validate the new site at: http://mechanics.flite.com

Happy Blogging!