GitHub Pages publishing from master vs master/docs or gh-pages branch

Question

I've been able to publish GitHub sites under my domain on GitHub Pages from the master branch without issue, however in the docs it says to use a gh-pages branch or master/docs for publishing projects. I also have a repository for my homepage index.html file/assets, where I link to each of the published GitHub repositories (which are published to my domain name.com/repo-name).

Why have I been able to publish from the master branch? Is there any reason to publish from the gh-pages branch or master/docs instead for publishing project repositories?

Answer 1

GitHub Pages can publish from any of those sources: gh-pages branch, master/docs, or just from the repo itself. It's more of a preference which route you use.

For example, Jekyll is publishing using the master/docs option. The rest of the repo outside of the docs folder is for the actual Jekyll code. One possible reason is that PR's with new features must also include documentation of that new feature. Otherwise, it won't get merged.

The gh-pages option means that code and documentation can be paced or managed differently. They live in the same repo, but the branches can grow at differing speeds.

In terms of technical differences, there's no technical costs/benefits to each option as far as I know. It's just how you want to organize your code and documentation.

Hope that helps!

Answer 2

GitHub requires user and organization sites to build from master , while project sites can build from gh-pages . If I understand correctly, you are publishing to your user site, ie yourusername .github.io.