Understanding Jekyll and the gh-pages branch when using GitHub Pages

3
votes

I'm using Jekyll with GitHub Pages (specifically, a project page). I've created 2 branches:

  1. master
  2. gh-pages

The documentation explains that the website content is stored in the gh-pages branch and that content will be rendered by Jekyll. The output will be available at a URL such as username.github.io/project-name.

If I run jekyll new mysite in my local master branch, that creates _config.yml, _posts, _sites etc in that branch. At this point if I run jekyll serve I can see a basic site at localhost:4000 (which is great).

My question:

Considering what I currently have in my master branch currently seems to be working, what is the purpose of the gh-pages branch? What exactly should be contained in a) master branch and b) gh-pages branch?

Thanks in advance.

2
gitgithubjekyllgithub-pages
You do not need the master branch if you want to publish a project website. You will only need gh-pages branch. So, you can delete the master branch after creating the gh-pages branch. Then you upload your website content to gh-pages; doesn't matter if you upload Jekyll folders (so GitHub will build your site) or if you upload your _site folder (so GitHub will only display your files as a web server would). That's it. – Virtua Creative
Thanks @VirtuaCreative, there seems to be two approaches I could take. See this answer. I'm wondering what approach people usually take with regards to using Jekyll with GitHub pages? – henrywright
you're welcome. I believe you need to understand the locally build of Jekyll. Suppose you want to upload a Jekyll website to a common Apache web server (not GitHub Pages). You upload the _site folder that Jekyll built locally to you. Now, when using GitHub as your host, you can do either, as GitHub builds it automatically for you. About user/organization and project websites in GitHub, the thing is: you can have as many websites as you wish. One for user/organization and multiple for projects. I recommend you to read this article for a better overview. – Virtua Creative
If you don't have any fancy plugins, the way most of developers do is uploading the Jekyll folder to gh-pages branch and setting GitHub to ignore the local _site folder. And if you don't need master branch, go on and delete it! And if you don't need more than one website, go for user website, not project. I say that because if you create a project site you will have this domain name: username.github.io/project. If a visitor tries username.github.io he'll find a 404 error. Hope to have helped! – Virtua Creative

2 Answers

4
votes

Reading Github pages documentation :

If you want to push your code and have Github generating your site :

You will only need to version your code and NOT the generated pages. So, only one branch is needed.

  1. For a user/organisation Github page (github.com/username/username.github.io), you publish your code in master.
  2. For a project page (github.com/username/projectRepository), you publish your code in gh-pages. Here you don't need a master branch.

If you need to generate your site locally and only send the generated pages on Github :

You will need to version both your code and you generated pages. So, two branches will be needed.

  1. User/organisation repository : base code goes in code (or whatever you name it) branch, and generated pages goes in master.
  2. Project repository : base code goes in master (or whatever you name it) branch, and generated pages goes in gh-pages.
0
votes

As described in github gh-pages:

Roll vanilla, or generate a site for your project to quickly get started.

gh-pages are simply a github specific branch which allow you to use it as your web site.

It means that if you have index.html in this page you will be able to view it in your browser directly.

you this link format: username.github.io/project_name

More info can be found here: https://pages.github.com/