Octopress documentation can be quite confusing. It took me a while to understand what the heck Octopress is doing to branches and remote origins. It’s actually pretty simple, so I am going to try to un-confuse you. I will also show you a better way to contribute to an existing blog and explain what’s happening in those Rake tasks.
We are going to deploy a blog to Github pages, so we need a project, such as username.github.com. Go to Github to create one. Use your username instead of “username”.
Next, fetch Octopress and install it locally. This gets the files from its main repository and applies a default theme.
$ git clone git://github.com/imathis/octopress.git octopress Cloning into octopress... remote: Counting objects: 6046, done. remote: Compressing objects: 100% (2420/2420), done. remote: Total 6046 (delta 3448), reused 5549 (delta 3097) Receiving objects: 100% (6046/6046), 1.26 MiB | 426 KiB/s, done. Resolving deltas: 100% (3448/3448), done. $ cd octopress Using /home/dblock/.rvm/gems/ruby-1.9.2-p290 octopress$ bundle install Fetching source index for http://rubygems.org/ ... Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed. octopress$ rake install ## Copying classic theme into ./source and ./sass
Octopress comes with some handy Rake tasks to get you started. To deploy to Github pages run
rake setup_github_pages. When prompted, enter the GIT URL to your new repository, such as firstname.lastname@example.org:username/username.github.com.git.
octopress$ rake setup_github_pages Enter the read/write url for your repository: email@example.com:username/username.github.com.git Added remote firstname.lastname@example.org:username/username.github.com.git as origin Set origin as default remote Master branch renamed to 'source' for committing your blog source files Initialized empty Git repository in /home/username/source/octopress/_deploy/.git/ [master (root-commit) 2a4e9e7] Octopress init 1 files changed, 1 insertions(+), 0 deletions(-) create mode 100644 index.html --- ## Now you can deploy to http://username.github.com with `rake deploy` ##
So what the heck happened here? It pointed our clone to our new repository. It also created a _deploy directory with another git repository that is going to contain everything that is being deployed. The remote in that directory is the same as the one in our octopress directory, but the checked out branch is master. Btw, we’re now on the source branch.
octopress$ git remote -v octopress git://github.com/imathis/octopress.git (fetch) octopress git://github.com/imathis/octopress.git (push) origin email@example.com:username/username.github.com.git (fetch) origin firstname.lastname@example.org:username/username.github.com.git (push) octopress$ git branch * source octopress$ cd _deploy/ octopress/_deploy$ git remote -v origin email@example.com:username/username.github.com.git (fetch) origin firstname.lastname@example.org:username/username.github.com.git (push) octopress/_deploy$ git branch * master octopress/_deploy$ cd .. octopress$
Now is a good time to read Blogging Basics. You should edit __config.yml _with your blog name, etc. Let’s create an article and deploy it.
octopress$ rake new_post["New Post"] Creating new post: source/_posts/2012-01-17-new-post.markdown
Edit the generated file and add some text at the bottom.
Generate the blog.
octopress$ rake generate ## Generating Site with Jekyll directory source/stylesheets/ create source/stylesheets/screen.css Configuration from /home/dblock/source/o/octopress/_config.yml Building site: source -> public Successfully generated site: source -> public
You can also preview it with
Before we deploy the blog, save the source and push it to Github. Note that we’re pushing our source branch.
octopress$ git add . octopress$ git commit -m "Initial blog post." ... octopress$ git push origin source Counting objects: 3927, done. Compressing objects: 100% (1412/1412), done. Writing objects: 100% (3927/3927), 910.08 KiB, done. Total 3927 (delta 2257), reused 3848 (delta 2203) To email@example.com:username/username.github.com.git * [new branch] source -> source
You’ll have to repeat the above every time you make changes, to save them.
Deploy the blog. What this does it rake everything inside _deploy and push it onto the master branch.
octopress$ rake deploy ## Pushing generated _deploy website Counting objects: 84, done. Compressing objects: 100% (74/74), done. Writing objects: 100% (84/84), 180.40 KiB, done. Total 84 (delta 2), reused 0 (delta 0) To firstname.lastname@example.org:username/username.github.com.git * [new branch] master -> master
If you go to http://username.github.com you should see your blog with the blog post once Github has regenerated the pages – usually a minute or two. And on https://github.com/username/username.github.com you should be able to see the generated files on master along with a source branch with the blog source.
You’ll have to do this every time you want to deploy your changes.
So how does one start contributing to an existing Octopress blog (or yourself from a new computer)? What we want is the same setup as above, but not from scratch.
$ git clone email@example.com:username/username.github.com.git $ cd username.github.com username.github.com$ git checkout source username.github.com$ mkdir _deploy username.github.com$ cd _deploy username.github.com/_deploy$ git init username.github.com/_deploy$ git remote add origin firstname.lastname@example.org:username/username.github.com.git username.github.com/_deploy$ git pull origin master username.github.com/_deploy$ cd .. username.github.com$
You’re all set. Create posts and stuff. Happy blogging with Octopress.