Deploying Jekyll to Github Pages

Question

I have built a site locally with Jekyll, and have pushed it to a new master repo (username.github.com) and the site works great yay. My question is, how do I move just the deployable part, the _site directory, into a gh-pages branch? Or rather, the contents of that directory if that is the best way to deploy?

I plan on using a custom domain. My workflow will be to work in the master branch, maybe some feature branches, and then push (merge) the compiled outcome into the gh-pages branch. Does that sound correct?

I am having a tough time figuring it out via documentation, would appreciate any help, thank you!

Answer 1

Your workflow does not sound correct based on the details in your question.

If you have pushed your Jekyll-based site to a username.github.io repository, then you do not need a gh-pages branch. A gh-pages branch is only required for repositories where you want to have code and a website in the same repository. GitHub Pages will take care of running Jekyll for you and serving the compiled site in both cases.

GitHub Pages does run Jekyll in a very specific manner in order to keep it safe. If you're using custom plugins with your Jekyll site, then you'll need to store your compiled site (the _site directory you mentioned) on the master branch, and the source in a different branch.

To summarize, your workflow should be work in your local repository - either in the master branch or feature branches (merging the feature branches to your local master branch as needed) - and when you're ready to publish, push your local repository to the master branch on GitHub.

Answer 2

What you wish to do is very similar to how Octopress works. Let me explain to you how you can do something like this.

You wish to deploy the data which is present in _site to the branch gh-pages. So, your first step will be to make the default branch for your repository username.github.com to be gh-pages and not master or source (basically whatever you want it to be). What you need to do now is write tasks in your Rakefile that copy the contents of _site to branch gh-pages. Once that is done, you can automate the push procedure or do it manually. That way, GitHub will not build your website when you push your default branch, instead it will just server the static pages that are present in _site.

If you want to understand how the scripts work, you should take a look at the Rakefile present in Octopress. It has these two tasks called as generate and deploy. When you run rake generate, it will run jekyll --no-auto with parameters for putting the code into a directory called _deploy and when you run rake deploy, it copies the content of _deploy to branch gh-pages and makes commit. Personally, I like this procedure a lot but I haven't implemented it in my Jekyll site as such.