Setting Up A Free Blog

How to set up a free blog using Octopress 3, GitHub Pages, git and a few other free tools.

Results This Tutorial

Tools Required

This tutorial assumes usage and familiarity with the following tools:

New Tools Used

Jekyll and Octopress 3

This tutorial uses git and GitHub for source code control, and if you check out GitHub Pages you’ll see that they “support Jekyll, a simple, blog-aware static site generator.” (from Using Jekyll with Pages).

Jekyll allows you write your blog and website in Markdown in text files. With a simple build command Jekyll converts these into static html pages.

There are other alternatives such as Hyde or WordPress, use google if you want to find out more.

Since this tutorial is using git to store the blog and website, it leads to a simple work flow for creating a blog post:

Jekyll itself is written in Ruby and is a fairly complex and low level framework. To make life simple this tutorial will use Octopress 3 on top of Jekyll.

From Octopress home page:

Octopress is a framework designed by Brandon Mathis for Jekyll, the blog aware static site generator powering Github Pages. To start blogging with Jekyll, you have to write your own HTML templates, CSS, Javascripts and set up your configuration. But with Octopress All of that is already taken care of.

NOTE: As of December 2014, Octopress is at version 2, and version 3 is being actively developed and documented as a release candidate. Hopefully by the time you’re reading this it will have been released, well tested and documented.


Markdown is a simple plain text based formatting language which is typically converted into HTML to render on a web page.

By default Jekyll and Octopress 3 use Markdown text files to represent blog posts. Also GitHub uses Markdown for it’s wiki, and README files, so knowing this will be useful.

Alternatives to Markdown such as Kramdown, Textile and others exist and might be supported by Jekyll and Octopress 3.

For example the following is Markdown text:


A list of things that are **important**:

* Sandwiches
* Snow
* Books

In a browser, using the default Octopress 3 theme, this would look like:

Example Output

The equivalent generated HTML would be:

<h1 id="title">Title</h1>

<p>A list of things that are <strong>important</strong>:</p>


The general idea is that Markdown is easier to read and write, but you can include HTML if you need more control or something specific that Markdown does not provide.


You may or may not be familiar with Ruby. For this tutorial you’ll only need to ensure it’s installed and install Ruby Gems which is pretty easy.

Generally it’s worth learning Ruby so you can go deeper into Jekyll, Octopress 3 and many other useful tools and applications.


YAML is a data serialization standard. Jekyll and Octopress 3 use this in some configuration files. It’s also used by many other tools and applications, so it’s worth learning too.


Check Ruby Is Installed

Typically Ruby is installed on most Unix-like operating systems. As mentioned earlier, this tutorial uses Mac OS X Yosemite 10.10, but you’ll likely have something different.

Let’s see if Ruby is installed already:

$ type -p ruby
$ ruby -v
ruby 2.0.0p481 (2014-05-08 revision 45883) [universal.x86_64-darwin14]

If you have Ruby version 2.0.0 or later you’re probably good to go.

As shown above, on Mac OS X the default version of Ruby is /usr/bin/ruby. This is the system version and installing Ruby gems will require you to be super-user or use sudo, which is not advisable.

The best solution is to install a local up-to-date version of Ruby, one good way to do this on Mac OS X is to use Homebrew package manager.

By default Mac OS X does not have Homebrew, so you may need to install it. See the Homebrew Install page, which on Dec 2014 says:

$ ruby -e "$(curl -fsSL"

If you already have Homebrew, you probably know the drill to install ruby:

$ brew update
$ brew install ruby
$ ruby -v
ruby 2.2.0p0 (2014-12-25 revision 49005) [x86_64-darwin14]

Other operating systems will have different ways to install ruby. However once that is done, installing Ruby Gems is usually the same across all platforms.

Install Jekyll and Octopress 3

Next install Jekyll and Octopress 3:

$ gem install octopress --pre
Fetching: fast-stemmer-1.0.2.gem (100%)
Building native extensions.  This could take a while...
# lots of similar output for about a minute ...
$ type octopress
octopress is /usr/local/bin/octopress

So far so easy. Installing Octopress 3 automatically installs Jekyll as a dependency. See Octopress 3 for more details.

NOTE: The --pre option is required until Octopress 3 is officially released.

Create Blog Locally

Now you can create the bare bones Octopress and Jekyll directory, which contains the most basic website and a single example blog post.

For personal GitHub Pages the repository on GitHub has to be called, where NAME is your account name, so for consistency we keep the directory and repository name the same. See GitHub Pages Help for more help.

NOTE: Replace NAME with your GitHub account name.

$ octopress new
New jekyll site installed in /Users/NAME/Projects/ 
Octopress scaffold added to /Users/NAME/Projects/

Preview Blog Locally

The previous step created enough data that Jekyll can build and view the equivalent static HTML site.

The command jekyll serve will:

$ jekyll serve &
Configuration file: /.../
            Source: /.../
       Destination: /.../
 Auto-regeneration: enabled for '/.../'
Configuration file: /.../
    Server address:
  Server running... press ctrl-c to stop.

As the command output shows we can open the local web page. Neat trick is that on Mac OS X the command open will do this for us:

$ open

Initialise and Commit To Git Locally

NOTE: Replace NAME with your GitHub account name.

$ cd
$ git init
Initialized empty Git repository in /.../
$ git branch -m source
$ git add .
$ git commit -m 'Initial commit.'
[master (root-commit) b6f0c3c] Initial commit.
 19 files changed, 820 insertions(+)
 create mode 100644 .gitignore
 # lots of files ...

Notice that the source to the blog should not be the master branch, the example above renames the initial branch to source.

With Octopress 3 as of Dec 2014, the best way to publish to GitHub Pages will be to locally generate the site HTML and push that to the master branch on GitHub. Fortunately as we’ll see octopress deploy to do this.

Therefore locally and on GitHub we’ll have two (or more branches):

Perhaps in the future GitHub will support Octopress 3 and you will be able to just push source, but as it currently stands the GitHub version of Jekyll has trouble with plugins (and also you’d probably have to keep in sync). This is a shame, and somewhat unexpected, but only makes our life a little harder.

Push Source To GitHub

First you’ll need create your GitHub Pages personal page repository on GitHub:

Once done you can push the local git repository source up to GitHub. Replace NAME with your GitHub account name, and REMOTE with the name of the remote used to push to. Good examples might be origin or github. Also note that the remote URL assumes you’re using ssh connections to GitHub.

$ git remote add REMOTE
$ git push --set-upstream REMOTE source

Set Up Deployment Of Website To GitHub

So far you have only pushed the source branch containing the Octopress 3 and Jekyll configuration and Markdown. GitHub serves your blog from the master branch.

Fortunately Octopress 3 has the octopress deploy command which automates the whole procedure.

In my experience any subsequent deployments of blogs markdown and web content (assets, html) after this cause the website to update very quickly (under a minute), but configuration changes to Jekyll and Octopress 3 seem to take up to half an hour.

Optional: Create a Custom Domain

You might be happy with hosting your blog at but typically registering a new domain and setting up DNS redirection is pretty cheap.

I personally use Namespro, since they’re reasonably priced (about $60 for two domains over two years), have all the features I wanted (domain name registration, DNS provider, WHOIS privacy) and local to me in Vancouver, Canada.


See for more details.

Personalize The Default Blog

Currently the default blog created by octopress new is generic and not personalized with your information. We should certainly fix this now everything seems to be working.

Improved Code Blocks

The default set up of Octopress 3 does not include very pretty code blocks, so lets fix that at least.

  - octopress-codefence
  - octopress-solarized

Write Your First Blog

```bash $ octopress new post "My First Post" ```

Go Crazy

You might want to do more crazy things later:

Some of these might be a subject for a future tutorial.

comments powered by Disqus