Octopress/Octopress with Github Project Pages

This guide covers how I installed Octopress for Github pages.

Installation

Create Your Project Repo

I assume you know how to make a new repo. Now you just clone your repo. I'll use the project I was working on, cantera-book:

git clone https://github.com/charlesreid1/cantera-book

Create Your Project Github Page

Github project pages work differently from Github user pages.

For a user page, the Octopress source code is contained in the source branch (or, whatever branch you want), and the live static content is deployed to the master branch (not whatever branch you want).

However, for Github project pages, the source code is contained in the master branch (or, whatever branch you want), and the live static content is deployed to the gh-pages branch (not whatever branch you want).

Thus, you can create your Github project page by creating a gh-pages branch:

cd cantera-book/
git checkout --orphan gh-pages

If you made a basic index.html in this directory, and committed your change to the repo, it would show up on your Github project page.

But we will let Octopress make the content. Switch back to the master branch:

git checkout master

Install Octopress Files

Use the Octopress repo from imathis (https://github.com/imathis/octopress), or fork it and make your own flavor of Octopress.

You need to copy all the Octopress repository files into their own directory project/octopress/.

But this is where things get hacky.

Deploying an Octopress to a Github project page did NOT work for me if octopress was living as a cloned copy of the Octopress repo (with the full history of imathis's Octopress repo) inside your project's Github.

So I had to copy the non-git files, like this:

cp -r /path/to/githubrepo/octopress/* /path/to/project/cantera-book/octopress/.
cp -r /path/to/githubrepo/octopress/.themes /path/to/project/cantera-book/octopress/.

Now you should be ok.

Install Theme

Install your theme,

cd cantera-book/octopress
bundle exec rake install

Setup Github Pages

bundle exec rake setup_github_pages

WARNING: Potential Octopress bug here. I fed my project page, but it ignored the name of the project page and tried to call the project "github". It deployed everything to subfolders called "github," and just acted weirdly. to get it to work, I ended up having to manually edit some config files.

Edit Config Files

Edit _config.yml:

line: 19
before: subscribe_rss: /github/atom.xml
after: subscribe_rss: /atom.xml

line: 29
before: root: /github
after: root: /

2. Set up your Octopress to work with Github pages:

cd project/octopress/
bundle exec rake setup_github_pages

3. Install your themes 3. Make your posts, change your site, do whatever

4. bundle exec rake generate && bundle exec rake deploy to generate static HTML files for site in _deploy

5. When happy with static HTML site, cd project/octopress/_deploy && git add . && git commit -am "Updating gh-pages branch" && git push origin gh-pages

6. When happy with site changes, posts, etc., cd project/octopress && git add . && git commit -am "Updating octopress site source" && git push origin master