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

Question

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.

Answer 1

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.

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