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.
Create a new Github repo named
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
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
All the Octopress code used to generate the website into the
now lives in new branch called
source. Note in the
source branch the
_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
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
$ 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
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
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
This is where the main site configuration lives. Things like the blog title and various 3rd Party Settings, your Twitter and Github handles etc.
_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
Github have full details on how to do this in their GitHub Pages Documentation.
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
www just point a
CNAME record to yourgithubusername.github.io
Working from another machine
_deploy directory is in the
.gitignore, the easiest thing is to clone
source branch and then setup the
_deploy branch manually.
$ git clone -b source firstname.lastname@example.org:username/username.github.io.git username.github.io $ cd username.github.io $ bundle install $ mkdir _deploy $ cd _deploy $ git init $ git remote add origin email@example.com:username/username.github.io.git $ git pull origin master $ cd ..