|   git, octopress | Comments

How to Set Up Octopress and Push to Github Pages

This is my first time setting up a blog using Octopress/Jekyll and hosting it on Github Pages. I wanted to document the process so I could remember it and also share it with others. Any comments or corrections are welcome.

Initial Setup

Please note that I’m working off a Macbook Pro with OSX 10.9.5.

So you will need git to save your blog posts to github. You’ll also need to install ruby because Octopress is built on that programming language.

  1. Get a github account
  2. Get Git
  3. Setup Git and learn how to fork a repo
  4. Install homebrew:
    ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  5. Then install rbenv using homebrew https://github.com/sstephenson/rbenv#homebrew-on-mac-os-x
  6. Run ruby --version in your terminal to make sure you’re running at v1.9.3 or higher

Setup Octopress

The original setup blog post can be found here: http://octopress.org/docs/setup/

  1. Login to github and go to Octopress
  2. At the top right of Octopress’ [repo page], fork the repo by click on the Fork button at the top right
  3. You should have a fork of Octopress in your own repo, like I do at https://github.com/jonathanxie/octopress
  4. Clone your own fork to your Desktop by using Github’s desktop client or with the following commands in terminal: git clone https://github.com/YOUR_GIT_USERNAME/octopress.git - Make sure to use your git username here.
  5. Go to cloned repo you just created: cd octopress
  6. Download Octostrap3 theme into a hidden directy called .themes:
    git clone https://github.com/kAworu/octostrap3 .themes/octostrap3
  7. Run: gem install bundler
  8. If you are using rbenv, run: rbenv rehash
  9. Run: bundle install
  10. Install the Octostrap 3 theme: rake 'install[octostrap3]'
  11. Generate the pages: rake generate 12 Test drive the blog by starting the built in web server: rake preview watch
  12. Go to your browser such as Google Chrome and go to: http://localhost:4000


Here are the steps 4-9 that you would execute line by line in your terminal:

In terminal, push CTRL-C to stop the web server.

Git and Github

Now I will explain some things about git. Earlier you created a fork of Octopress to your github account. My fork is at:

https://github.com/jonathanxie/octopress.git

Your fork would be at:

https://github.com/YOUR_GITHUB_USERNAME/octopress.git

Please take note that URL address is what git considers a remote repository. Then you cloned Octopress from this remote repository into a Desktop directory called Octopress by using Github’s desktop application or with the following command:

1
2

cd ~/Desktop
git clone https://github.com/jonathanxie/octopress.git

Origin and Remote Repositories

This tells git to create a local copy of your forked Octopress to your desktop at ~/Desktop/octopress. One important thing to note is that git will set this remote repository as the origin for your local repository. When you commit your code from your local copy, all your changes will go to origin. origin points to the remote repository where you want to publish your commits. By default, the remote repository you cloned from is called “origin”, but you can work with several remotes that even have different names concurrently. This is a very important concept you will need to understand in this post, but you can learn more about remote repositories here.

To see your remote repositories, in your terminal type: git remote -v

For the output, you should see something like:

Output for: git remote -v 
1
2

origin  https://github.com/jonathanxie/octopress.git (fetch)
origin  https://github.com/jonathanxie/octopress.git (push)

As you can see, your origin for fetching and pushing code points to the remote repository you forked earlier.

Branching

Another important thing to note here about git is branching. A git repository can have multiple branches and you use git branches to develop code isolated from each other. An example of how branching looks like is shown here taken from Atlassian’s thorough branching tutorial:

Alt Atlassian's example of branching in git


Right now your local repository has one branch called master. To check what branch you are on, run the following command: git branch

You should see:

Output for: git branch 
1

* master

The * in front of master represents the current branch you are working on in the repository. So note that you are currently working in the master branch of your repository. When you run git init to create a local working repository or git clone https://github.com/jonathanxie/octopress.git to copy a remote repository, git will automatically create a master branch for you by default to start off with in your repository.

Now say for example, you and I are working on the same remote repository but developing different features. I can create a branch from the master branch called jonathan-feature-x and switch to that new branch. Then you could stay on the master branch without worrying about my chances until we merge code. The code would look like:

Code to create and switch to a new branch 
1
2

git branch jonathan_new_feature
git checkout jonathan_new_feature

git checkout is the way to switch to a new branch. When you run that command you should see the following output:

Output for: git new branch 
1

Switched to branch 'jonathan_new_feature'

Note that I could have also done this in one line with: git checkout -b jonathan_new_feature

Now run git branch and you should see:

Code to create and switch to a new branch 
1
2

* jonathan_new_feature
  master

Note the * next to jonathan_new_feature. This means you are now working on jonathan_new_feature instead of master. To switch back, just run: git checkout master and you will see:

Output for: git checkout master 
1
2

Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.

The status message saying Your branch is up-to-date with 'origin/master'. means that there are no merges or changes after switching branches.

You can now delete the newly created branch with: git branch -D jonathan_new_feature

You should see the following out:

Output for: git branch -D jonathan_new_feature 
1

Deleted branch jonathan_new_feature (was a311b68).

Run git branch again and you will see:

Output for: git branch 
1

* master

Creating your first blog post on Octopress

Now that you some understanding about git and Github, it’s time to create your first blog post. In terminal, run:

Code to create a new blog post 
1

rake new_post["Hello World"]

You should see the following output:

Output for: rake new_post[“Hello World”]
1
2

mkdir -p source/_posts
Creating new post: source/_posts/2014-10-11-hello-world.markdown

You can now edit the file using markdown at the following directory:

~/Desktop/octopress/source/_posts/2014-10-11-hello-world.markdown

I prefer to use Sublime Text and I’ve setup it up to use from command line. You can use any text editor but if you have Sublime Text like me, run the following command:

Run Sublime Text 
1

subl ~/Desktop/octopress

Then push Command-T in Sublime Text and type in 2014-10-11-hello-world.markdown in the file search dialog bog and open that file. You will then see [front matter](http://jekyllrb.com/docs/frontmatter/) text:

Front Matter at top of markdown file 
1
2
3
4
5
6
7

---
layout: post
title: "Hello World"
date: 2014-10-13 16:04:07 -0700
comments: true
categories: 
---

Add something simple below that: Hello World! This is my first post!

Save the file, then run: rake preview watch and go to: http://localhost:4000

You will see a blog post called Hello World and the url should be:

http://localhost:4000/blog/2014/10/13/hello-world

Saving your code to Github

Now that you have your first blog post, it’s time to save your it to your repository.

Run the following command: git status

You should see the following output:

Output for: git status 
1
2
3
4
5
6
7

On branch master
Untracked files:
  (use "git add <file>..." to include in what will be committed)

  source/_posts/2014-10-11-hello-world.markdown

nothing added to commit but untracked files present (use "git add" to track)

So you’re on the master branch with an untracked file: source/_posts/2014-10-11-hello-world.markdown

Run this command to add the file: git add source/_posts/2014-10-11-hello-world.markdown

Now the file is added and tracked by git. Next run: git commit -m "Adding Hello World blog post"

Then you should see:

Output for: git commit - m “Adding Hello World blog post” 
1
2
3

[source c779ac2] Adding test file
 1 file changed, 7 insertions(+)
 create mode 100644 source/_posts/2014-10-14-hello-world.markdown

Now your changes have been committed to your local copy of the repository but you have to push them to your remote repository. Remember you’re on the master branch right now and your remote repository is called origin. So you need to tell git to push your committed changes from the master branch of your local repository to the master branch of the remote repository at origin

Run: git push origin master

You should see something like:

1
2
3
4
5
6
7

Counting objects: 18, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 340 bytes | 0 bytes/s, done.
Total 4 (delta 3), reused 0 (delta 0)
To https://github.com/jonathanxie/octopress.git
   ca939a8..8c84805  master -> master

Setting up Octopress to deploy to Github Pages

Now that you have successfully pushed your code to github, it’s time to setup your blog so that Github Pages can host it. The original tutorial on Octopress’ site is here.

Github Pages allows for free hosting of your blog! So first go to your github account and create a repository called username.github.io, where username is your GitHub user name or organization name. Do not add an LICENSES or README files just yet when you set up the page. You will need a clean repository.

My repository is called jonathanxie.github.io and you can go to https://jonathanxie.github.io to view my blog too. I’m able to use http://www.jonxie.com because I have a custom domain with Github Pages, which you can read about here.

Now copy your repository’s HTTPS url, it should looking something like:

Example of Github blog repository URL for Github Pages 
1

https://github.com/jonathanxie/jonathanxie.github.io.git

Go back to the terminal and run the following command to setup deployment to Github Pages:

Command to setup Octopress for Github Pages 
1

rake setup_github_pages

This rake task will:

  1. Ask for and store your Github Pages repository url: git@github.com:YOUR_GITHUB_USERNAME/YOUR_GITHUB_USERNAME.github.io.git

    Note that my repository with a SSH link is: git@github.com:jonathanxie/jonathanxie.github.io.git

  2. Rename the remote respository pointing to https://github.com/YOUR_GITHUB_USERNAME/octopress from ‘origin’ to ‘octopress’

  3. Add your Github Pages repository pointing to https://github.com/YOUR_GITHUB_USERNAME/YOUR_GITHUB_USERNAME.github.io.git as the default origin remote.
  4. Switch the active branch from master to source.
  5. Configure your blog’s url according to your repository.
  6. Create a directory called _deploy which contains your static code for your blog
  7. Setup a master branch in this _deploy directory
  8. Push the code in this new master branch to the new origin

Now if everything is setup correctly, you should be able to view your blog at:

http://YOUR_GITHUB_USERNAME.github.io

Branches and origins have changed

Note that your branch has changed from master to source as stated by step 4. Run: git branch

Output for: git branch 
1

* source

Also note that your remote repositories have changed as stated in Steps 2 and 7. Run: git remote -v

Output for: git remote -v 
1
2
3
4

octopress https://github.com/jonathanxie/octopress.git (fetch)
octopress https://github.com/jonathanxie/octopress.git (push)
origin  https://github.com/jonathanxie/jonathanxie.github.io (fetch)
origin  https://github.com/jonathanxie/jonathanxie.github.io (push)

rake deploy

IMPORTANT NOTE: Make sure to always run rake generate before rake deploy. If not, your changes in your code will NEVER get pushed to Github Pages.

Now when you run rake deploy, your code from the source directory will be compiled to the _deploy directory, which has master branch. rake deploy will also commit and push the code from the _deploy directory to the remote repository at origin: https://github.com/jonathanxie/jonathanxie.github.io

So you shouldn’t have to ever go into the _deploy directory to do anything.

Saving your code to your Octopress remote repository.

It is important to note that rake deploy does not save your code to your Octopress remote repository. You still need to save the code you typed up until now. To commit and push your code in the source directory to your Octopress repository at https://github.com/jonathanxie/octopress.git, run:

Code to commit and push your code to the Octopress remote repository 
1
2
3

git add -A 
git commit -m "Add some all modified and deleted files"
git push octopress source

You should see something like:

Output for: git push octopress source 
1
2
3
4
5
6
7

Counting objects: 20, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 1.48 KiB | 0 bytes/s, done.
Total 5 (delta 4), reused 0 (delta 0)
To https://github.com/jonathanxie/octopress.git
   8c84805..524526c  source -> source

git push octopress source means you are pushing from the source branch to octopress, which is a remote repository pointing to: https://github.com/YOUR_GITHUB_USERNAME/octopress.git

When you push from source to octopress, git will create a new branch in the remote repository on Github. So if you need to clone your repository again, you should use the following command (remember to change jonathanxie to your github username):

Command to clone the ‘source’ branch of your Octopress remote repository 
1

git clone https://github.com/jonathanxie/octopress.git -b source --single-branch

Setting Up SSH Keys and Github

If you don’t want to continually type in your username and password when you push to github, you can set up SSH keys described in more detail here.

The steps I took are:

  1. Run: ssh-keygen -t rsa -C jonxie@jonxie.com

  2. Push enter when you see the following output where ssh-keygen is asking you for a filename to save the key:

     Generating public/private rsa key pair.
 Enter file in which to save the key (/Users/jontse/.ssh/id_rsa):

  3. Since I didn’t have an SSH directory yet, ssh-keygen created one for me. It also asked me for a passphrase, which is a password, so enter the same passphrase twice

     Enter passphrase (empty for no passphrase): 
 Enter same passphrase again:

  4. Next you should see something similar to the following output:

     Your identification has been saved in /Users/jontse/.ssh/id_rsa.
 Your public key has been saved in /Users/jontse/.ssh/id_rsa.pub.
 The key fingerprint is:
 01:0f:f4:3b:ca:85:d6:17:a1:7d:f0:68:9d:f0:a2:db jonxie@jonxie.com
 The key's randomart image is:

  5. Run eval "$(ssh-agent -s)" and you should see output like:

     Agent pid 5888

  6. The add your ssh key to the ssh agent: ssh-add ~/.ssh/id_rsa

  7. Copy your ssh-key to your clipboard on Mac OS X: pbcopy < ~/.ssh/id_rsa.pub

  8. Go to SSH settings on github: https://github.com/settings/ssh, click on Add SSH key at the top right and then enter in the key you copied.

  9. Test everything out now with this command: ssh -T git@github.com

    You may see this output and if you do, make sure that the fingerpint matches the fingerprint you saw when you ran ssh-keygen. If it’s correct, then say yes to the question.

     The authenticity of host 'github.com (207.97.227.239)' can't be established.
 # RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48.
 # Are you sure you want to continue connecting (yes/no)?

  10. If everything is correct, then you should see something like:

    Hi jonathanxie! You've successfully authenticated, but GitHub does not provide shell access.

  11. Next you have to change your git remote URLs from https to ssh. To look at your remote repositories run:

    git remote -v

    octopress   https://github.com/jonathanxie/octopress.git (fetch)
octopress   https://github.com/jonathanxie/octopress.git (push)
origin  https://github.com/jonathanxie/jonathanxie.github.io (fetch)
origin  https://github.com/jonathanxie/jonathanxie.github.io (push)

    Notice that all entries start with https://. Those entries need to change to an SSH URL which looks like: git@github.com:USERNAME/YOUR_REPOSITORY.git

  12. Change the remote address octopress to use SSH:

    git remote set-url octopress git@github.com:jonathanxie/octopress.git

  13. Change the remote address for origin to use SSH

    git remote set-url origin git@github.com:jonathanxie/jonathanxie.github.io

  14. Now to see your changes to the remote repositories, run: git remote -v

    octopress   git@github.com:jonathanxie/octopress.git (fetch)
octopress   git@github.com:jonathanxie/octopress.git (push)
origin  git@github.com:jonathanxie/jonathanxie.github.io (fetch)
origin  git@github.com:jonathanxie/jonathanxie.github.io (push)

  15. Now if everything works fine and if you have committed changes in your repository,if you run: git push octopress source, it shouldn’t prompt you for your username or password anymore.

  16. If there are any issues, go to github’s help page for help.

References

Octopress

Git Guides

SSH and Git

Markdown for blogging

Comments