David Ruttka

I make computers do things

Setting Up Octopress for GitHub Pages

| Comments

Last time we looked at setting up GitHub Pages. Now we’ll get rolling with Octopress to generate our static content and deploy it seamlessly.

Installing Octopress

As with GitHub Pages, the official documentation is super solid, here. I’m going to attempt to give a more terse set of steps that I took, but do refer back to the docs if you need more information.

  • I already had Git and Ruby installed, so I got a free pass on that.
  • Clone the repo git clone git://github.com/imathis/octopress.git octopress
  • cd into it cd octopress
  • gem install bundler
  • bundle install.
  • rake install, and I actually did hit a snag here

    You have already activated rake 10.0.3, but your Gemfile requires rake 0.9.2.2.

  • All I had to do was update the Gemfile to reference 10.0.3 and rake install again.

Configuration

Start with rake setup_github_pages. This will ask where your repo is, and set up deployments accordingly.

Now, you probably also have a better title in mind than “My Octopress Site.” This, and much more, is in _config.yml. I changed the following, and left the rest alone:

  • url
  • title
  • subtitle
  • author
  • twitter_user

More information in the official docs for Configuration and Deployment.

Themes

I went to Octopress Themes and got a free one. I went the submodule route. Assuming you chose classic light, you’d do something like this.

  • From the directory where you cloned Octopress, git submodule add git://github.com/octothemes/classic-light.git .themes/light
  • git add .themes and commit
  • rake install[light] will apply it
  • rake generate and rake preview will let you see how it looks on localhost:4000
  • rake install[classic], with the following rake generate, will put things back if you don’t like it

FWIW, at the time of this writing, I’m using forest.

Hello, Octopress

rake new_post["Hello Octopress"] will generate a markdown file in source/_posts. It will have the correct date and title format, and all you have to do is fill in the content.

rake generate, and then rake preview.

That’s great for posts, what about pages

You might have guessed it, but rake new_page["About"]. This will generate a markdown file in {pagename}/index.markdown, and all you have to do is edit it.

Don’t forget to update your navigation to include your new page! You’ll find it in source/_includes/custom/navigation.html, at which point you’re just adding a link.

I removed the date, and turned off the sharing and footnote options for my About page. I just think it looks cleaner that way.

It’s not git push, it’s rake deploy

When you like what you’re seeing in rake preview, rake deploy. Given that you’ve already gone through the delay setting up the repo and CNAME, it’ll be live ridiculously fast.

Heads up! Remember when you put CNAME and an index.html in your repo before? I had to navigate into _deploy, and do a git pull resolving some conflicts before rake deploy could push successfully.

Heads up again! That CNAME that was in the root of your repo should now be in source. This will ensure it sticks around each time you rake generate.

Images

One thing I found while doing my About page was including images. The idea is as follows

  • Add the image to source/images
  • Use the image tag plugin: <img src="/images/the_image.jpg">
    • You can also specify left, right, [width] and [height], etc. Full docs here.

Comments