Octopress is a static blog generator. It uses Jekyll which was created by Github to run Github Pages and now I’m using it to power my re-launched blog.
I’m attracted by the prospect of using Octopress because it’s dead simple. It generates the blog content as flat pages so it’s super fast. It allows me to write using Markdown and deploy via Git.
There’s no server setup and no hosting fees, as it’s hosted using Github Pages. Also it’s written in Ruby, so it works with all the tools I’m familiar with.
What follows is more for my reference than anything, so I can remember how I set things up.
Initial setup
Create a new Github repo named yourgithubusername.github.io
.
The name is important here as Github Pages will automatically find this repo and
serve up the content it finds in the master
branch as your website at
http://yourgithubusername.github.io
.
Grab Octopress and change directory:
$ git clone git://github.com/imathis/octopress.git yourgithubusername.github.io
$ cd yourgithubusername.github.io
Octopress has its’ own rvmrc file, but I like to use gemsets, so I created my own before installing bundler and the required gems:
$ rvm use 1.9.3@yourgemsetname --create --rvmrc
$ gem install bundler
$ bundle install
Install the default theme:
$ rake install
Octopress has a configuration rake task that automatically sets the repo up for easy deployment to Github Pages:
$ rake setup_github_pages
This task does quite a few things. The most important is that it creates a new
_deploy
directory that is another git repository. This is where Octopress
generates the flat website for deployment to the master
branch of your repo
on Github.
All the Octopress code used to generate the website into the _deploy
directory
now lives in new branch called source
. Note in the source
branch the
.gitignore
includes _deploy
so it doesn’t get committed in two places!
This sounds more complicated than it is, Octopress has rake tasks to make this really easy to manage. It’s worth pushing up at this point to check everything works before tinkering:
$ rake generate
$ rake deploy
This copies the generated files into _deploy
, adds them to git, commits and
pushes them up to the master
branch.
Visit http://yourgithubusername.github.io
Note at this point only the website has been committed, the source needs to be comitted separately via:
$ git add .
$ git commit -m 'Initial source commit'
$ git push origin source
Running Octopress locally
The simplest thing to do is fire up your site on http://localhost:4000
via:
$ rake preview
Alternatively, Octopress works really well with POW server.
$ cd ~/.pow
$ ln -s /path/to/your/octopress/site yoursitename
Now that you’re setup with POW, in the root of your source
branch run:
$ rake watch
Load up http://yoursitename.dev
Theme customisation
I’m using the ‘Whitespace’ theme by lucaslew. Other themes are available.
I’ve tweaked the header to remove the search and include navigation links to my Twitter and Github accounts.
I installed the theme by running the following in the root of the source
branch.
Say yes when it asks you to overwrite existing files.
$ git clone git://github.com/lucaslew/whitespace.git .themes/whitespace
$ rake install['whitespace']
$ rake generate
_config.yml
This is where the main site configuration lives. Things like the blog title and various 3rd Party Settings, your Twitter and Github handles etc.
Changes to _config.yml
will require you to restart the rake watch
task if
you’re using POW server.
Creating this post
As easy as:
rake new_post["Hello Octopress and Github pages"]
Deploying to Github Pages
$ rake generate
$ rake deploy
Just rememeber to manually commit changes made in the source
branch.
Custom domain
Github have full details on how to do this in their GitHub Pages Documentation.
Inside your source
branch run the following:
echo 'your-domain.com' >> source/CNAME
Regenerate your site and deploy up to Github. In your DNS settings point an
A record
(for your naked domain) to 204.232.175.78
.
For www
just point a CNAME record
to yourgithubusername.github.io
Working from another machine
As the _deploy
directory is in the .gitignore
, the easiest thing is to clone
the source
branch and then setup the _deploy
branch manually.
$ git clone -b source git@github.com:username/username.github.io.git username.github.io
$ cd username.github.io
$ bundle install
$ mkdir _deploy
$ cd _deploy
$ git init
$ git remote add origin git@github.com:username/username.github.io.git
$ git pull origin master
$ cd ..