Deploying Octopress Blog to an Existing Gh-pages Static Site

The issue I faced was that I have an existing static site hosted on Github via gh-pages. That is just regular HTML/CSS/JS. It works perfectly.

But, I wanted to add an elegant Octopress blog to that same static site - so I can have both my company site & blog hosted on Github’s powerful hosting platform.

This is how I pulled it off.

  • Get the folder of your static site all setup like normal. Get all the pathings right for your /img, /css, /js, etc.
  • Follow all the directions in the Octopress setup and deployment guide.
  • Install the theme you want for Octopress (it is important to do this step before the rest of the steps, because everytime you install a theme it resets your index.html).
  • Follow these instructions about moving your blog index page - make sure to update the Rakefile, per the instructions.
  • Then use these settings in your files:

_config.yml (you can customize all the other settings, but these worked for me)

url: http://5kmvp.com
subscribe_rss: /atom.xml
root: /
permalink: /blog/:year/:month/:day/:title/
source: source
destination: public
category_dir: blog/categories

Rakefile

public_dir      = "public"    # compiled site directory
source_dir      = "source"    # source file directory
blog_index_dir  = 'source/blog'    # directory for your blog's index page (if you put your index in source/blog/index.html, set this to 'source/blog')

Then once that is done, you copy your existing static site (with the exact structure that you setup earlier) into your /octopress/source/ folder - so yours should look similar to mine here.

What you will notice is that now Octopress will publish to /blog (which is a subfolder called ‘blog’ in your ‘source’ folder).

Basically the way Octopress works is that at it’s core, it copies everything from /source/ except for a few exceptions (all folders that start with _, etc.)

If you have any conflicts with your folders (e.g. if you have /img/ and Octopress has /images/) then just copy both if you don’t want have to update your paths in all your HTML files. It’s no big deal.

That’s pretty much it.

Remember that rake preview and rake generate are your friends. Use them religiously.

If you have any issues with styling, then you may need to play around with some of the paths in the various variables in your _config.yml and Rakefile a bit. But you should’t have to, because all of these values worked for me - and I did A LOT of playing around.

Special Note: You should end up with your static site index.html in the root folder of the generated site - you can see the source here and the generated version here - and you should also have an octopress generated index in the /blog/ subfolder - again…the source here and generated version here.

You can always just look at my entire source to see what I did.

Most other setup & deployment instructions apply and work fine (including remembering to include a CNAME file for your custom domain).

Whenever you want to change one of the static sites - i.e. a non-octopress file - then edit/update it locally and use rake deploy when you are done (as opposed to a git push like you would for a normal non-static site hosted on gh-pages).

Remember to backup your entire repo to a source or master branch or some other branch, so you can always revert to it if you mess stuff up.

Good luck and I hope this saves some poor soul from spending weeks trying to figure this out.

Comments