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.
- Get a github account
- Get Git
- Setup Git and learn how to fork a repo
- Install homebrew:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
- Then install rbenv using homebrew https://github.com/sstephenson/rbenv#homebrew-on-mac-os-x
- 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/
- Login to github and go to Octopress
- At the top right of Octopress’ [repo page], fork the repo by click on the Fork button at the top right
- You should have a fork of Octopress in your own repo, like I do at https://github.com/jonathanxie/octopress
- 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. - Go to cloned repo you just created:
cd octopress
- Download Octostrap3 theme into a hidden directy called .themes:
git clone https://github.com/kAworu/octostrap3 .themes/octostrap3
- Run: gem install bundler
- If you are using rbenv, run:
rbenv rehash
- Run:
bundle install
- Install the Octostrap 3 theme:
rake 'install[octostrap3]'
- Generate the pages:
rake generate
12 Test drive the blog by starting the built in web server:rake preview watch
- 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 |
|
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:
1 2 |
|
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:
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:
1
|
|
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:
1 2 |
|
git checkout
is the way to switch to a new branch. When you run that command you should see the following output:
1
|
|
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:
1 2 |
|
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:
1 2 |
|
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:
1
|
|
Run git branch
again and you will see:
1
|
|
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:
1
|
|
You should see the following output:
1 2 |
|
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:
1
|
|
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:
1 2 3 4 5 6 7 |
|
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:
1 2 3 4 5 6 7 |
|
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:
1 2 3 |
|
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 |
|
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:
1
|
|
Go back to the terminal and run the following command to setup deployment to Github Pages:
1
|
|
This rake task will:
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
Rename the remote respository pointing to
https://github.com/YOUR_GITHUB_USERNAME/octopress
from ‘origin’ to ‘octopress’- Add your Github Pages repository pointing to
https://github.com/YOUR_GITHUB_USERNAME/YOUR_GITHUB_USERNAME.github.io.git
as the default origin remote. - Switch the active branch from
master
tosource
. - Configure your blog’s url according to your repository.
- Create a directory called
_deploy
which contains your static code for your blog - Setup a master branch in this
_deploy
directory - 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
1
|
|
Also note that your remote repositories have changed as stated in Steps 2 and 7. Run: git remote -v
1 2 3 4 |
|
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:
1 2 3 |
|
You should see something like:
1 2 3 4 5 6 7 |
|
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):
1
|
|
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:
Run:
ssh-keygen -t rsa -C jonxie@jonxie.com
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):
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:
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:
Run
eval "$(ssh-agent -s)"
and you should see output like:Agent pid 5888
The add your ssh key to the ssh agent:
ssh-add ~/.ssh/id_rsa
Copy your ssh-key to your clipboard on Mac OS X:
pbcopy < ~/.ssh/id_rsa.pub
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.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)?
If everything is correct, then you should see something like:
Hi jonathanxie! You've successfully authenticated, but GitHub does not provide shell access.
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
Change the remote address octopress to use SSH:
git remote set-url octopress git@github.com:jonathanxie/octopress.git
Change the remote address for origin to use SSH
git remote set-url origin git@github.com:jonathanxie/jonathanxie.github.io
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)
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.If there are any issues, go to github’s help page for help.
References
Octopress
- http://octopress.org/docs/blogging/
- http://octopress.org/docs/deploying/github/
- http://allenyee.me/blog/2013/08/21/what-i-learned-from-hosting-octopress-on-github/
- http://learnaholic.me/2012/10/10/deploying-octopress-to-github-pages-and-setting-custom-subdomain-cname/
- http://webdesign.tutsplus.com/tutorials/getting-started-with-octopress–webdesign-11442
Git Guides
- https://help.github.com/articles/set-up-git/
- http://rogerdudler.github.io/git-guide/
- http://gitref.org/remotes/
- https://www.atlassian.com/git/tutorials/using-branches/
- http://gitref.org/branching/#branch
- http://stackoverflow.com/questions/9529497/what-is-origin-in-git
- http://stackoverflow.com/questions/20033863/pull-specific-branch-from-git
SSH and Git
- https://help.github.com/articles/generating-ssh-keys/
- https://help.github.com/articles/changing-a-remote-s-url/
- https://help.github.com/articles/error-permission-denied-publickey/
- https://github.com/settings/ssh