What’ll we learn here?
Things we’ll cover before this post is through:
- Installing Ruby
- Getting Jekyll up and running on OSX (10.8.3)
- Installing Pygments for code highlighting
- GitHub Pages deployment and testing
- Your first post
If you’re running OSX 10.5 or higher, good news! Max OSX 10.5 and higher already ships with Ruby and RubyGems installed, so you don’t have to do anything.
While the official docs are readily available to everyone, getting Jekyll set up is painfully easy using ruby gems.
So, following the official docs, the best way to install jekyll is via RubyGems:
You may see this error (or something similar to it):
This error isn’t important if you just want Jekyll installed, and are happy to live without the documentation.
You’ll likely want some form of syntax highlighting in your own blog posts, so installing Pygments will make this easy.
As we’re running OSX here, Python 2.6 is preinstalled, so all you need do is:
However, if you want to use Homebrew (which, by the way, I recommend), you can do it like this:
####Note (lifted from the Jekyll install docs)
Homebrew doesn’t symlink the executables for you. For the Homebrew default Cellar location and Python 2.7, be sure to add
/usr/local/share/python to your
PATH. For, more information, check out this.
GitHub Pages is a freely hosted platform for publishing static websites using GitHub’s infrastructure. Controlled via a specially named repository, they allow for standard, static HTML sites to be hosted, or generated sites using Jekyll.
For those too lazy to read the docs, here’s the important information:
- There are 2 types of github-pages, User/Organisation, and Project
- User/Organisation types must use a repo with the following name:
username/username.github.io, and will be automatically published to (http://username.github.io) from the master branch
- Note that
usernamehere is swappable with the organisation’s name
- An example of this, is the blog you’re currently reading - (http://currencyfair.github.io)
- Project types must use the project repos themselves, but are automatically published from the gh-pages branch of your repository
- You can easily set up custom domains with pages, like with this blog, which is available on both (http://currencyfair.github.io) and (http://tech.currencyfair.com)
- To do this, you need to first tell GitHub that you will be pointing a domain at your repository, by creating a file called
CNAMEin the root of your master (or gh-pages) branch, containing just one line - the domain name that will be pointing to your GitHub Pages repo.
- An example: https://github.com/currencyfair/currencyfair.github.com/blob/master/CNAME-tmp
- Next, you need to add a DNS record to your domain to point to GitHub, so browsers will know where to go when you link to your custom domain
- For a TLD (
example.com), you should use an A record to point to
22.214.171.124(double check this IP on the GitHub docs - I’ll try to keep it up to date as changes happen though)
- For a subdomain (
tech.example.com), you should use a CNAME record to point to
Again, it’s well worth reading through the docs for GitHub Pages, but the steps above should serve you well if you just want to get up and running asap.
At this stage, you have Ruby installed, along with Jekyll & Pygments, and you have a github repo (possibly running on a custom/sub domain)… now, it’s time to post your first post.
To start with, we’ll take a look at the Hello World post on our own blog.
Here’s the raw code for the post itself:
--- layout: post description: "Hello World" category: general tags: - welcome - blog authors: - Paul Phillips intro: "Since starting three years ago, CurrencyFair has scaled massively as a business. Going from $50k transferred on day one to an amazing $500m transferred to date, and with a goal of $1b in the next twelve months, the company is definitely on the right track." image: hello-world.png --- ## History and some stats Since starting three years ago, CurrencyFair has scaled massively as a business. Going from $50k transferred on day one to an amazing $500m transferred to date, and with a goal of $1b in the next twelve months, the company is definitely on the right track. To achieve that goal, we need to be transferring nearly $3m / day - thats about $34 / second! As with any goal, the company needs a great group of people to achieve it and so we will also need to grow aggressively across all teams. These objectives and growth plans are dependent on a number of teams including marketing, customer service, payments and tech. Each team is going to face unique challenges as they try to achieve their goals and support the others. Without any one of these teams, things begin to fall apart. At a very high level: * Marketing aims to gain and retain customers * Customer service is the direct interface to our customers * Payments handles our customers money * Tech allows our customers to interact with the other teams Our posts here are going to focus on the tech team and the challenges we face as we grow and support the other teams. Every now and then we may dip into topics outside of tech, but only with the aim of putting the particular challenge into context. ## What will we talk about? Tech isn't just about the website. As I mentioned above, every team interacts with each other in different ways for support. In the early days of a startup at least, all teams will interact with each other. So, we will look at the different interactions that we have, the challenges we face and the solutions we use to overcome them. On a high level, we hope to look at topics like: * #processes * #tools * #languages * #frameworks * #infrastructure * #security Our aim is to share what we have learned and what we will learn, in a bid to learn more ourselves and to also show others what it's like to work at CurrencyFair. We also hope to opensource any tools that we develop that we think would be of benefit to the community. ## Who are we? We're a group of engineers who have worked in large corporations like IBM, and startups like scrazzl.com and hostelworld.com. You can hit us up on twitter here: [Paul](https://twitter.com/free2panik) or [Daniel](https://twitter.com/danielhunt). If you like the sound of CurrencyFair, why not [think about it](/2013/04/16/currencyfair-is-hiring).
###How does it work?
- The top section, between the
---lines, tell Jekyll information about this post. By default Jekyll understands a handful of keys in this list - we’ve added items, like ‘image’ and ‘authors’, to improve the look and feel of our own interface.
- Everything else is the post content itself, written in Markdown. I’ve been using DaringFireball’s markdown syntax page as a reference guide for the different tags available, and definitely recommend it.
- All GitHub Pages repos are required to be public, so if you want to know how we’ve gone about doing anything in particular, you can always just check the source of our posts themselves!
Every time you add, edit or delete a post, you’ll need to regenerate your static html from scratch, so that everything links up correctly (and for your edits to appear).
This is a painless process - all you need do is run
jekyll --server --pygments --safe --no-lsi, and your
_sites directory will be updated with the latest version of your blog (along with its posts)!
To access your new blog, simply point your browser at http://localhost:4000, and you should see your content there. This will allow you to review any new posts or updates as you go, without worrying about your live site being affected.
Once you’re happy with your content, commit & push your code up to GitHub. Within a few seconds, your new site will be live, and available for others to view!