Using gh-pages branch

I want to host solutions to exercises (discussion and code) for two programming books I’m writing. I’ve learned how to create a Pages site ( but am having trouble figuring out the structure of my site. I’m especially confused about the purpose of the gh-pages branch and the use of a project.

The documentation says, “The default publishing source for user and organization sites is the root of the default branch for the repository. The default publishing source for project sites is the root of the gh-pages branch.”

One site I saw used one repository for the book and placed the code files in the main branch. Then the author used the gh-pages branch of the same repository for the solutions documents (written in md) and the Pages files in the gh-pages branch. Using a branch this way seems odd to me. And the site does not have any projects. I am more inclined to use two separate repositories, one for the code, the other for the website. But I still have no idea where a project might come into play.

What am I missing here?

I think the idea is that you would have a branch for docs and a branch for code. However I agree that this goes against the idea of branches: that at some point they are theoretically meant to be merged. That said I don’t really understand what your question is.

Are you asking whether you should use a gh-pages branch? Personally I think it’s better to have a separate repository and put the docs/webpage/whatever on the main branch, but it’s really up to you.

Thank you, mattfbacon. Despite your not understanding my question, your response is precisely what I was looking for. I’m new to git – wish I started using it long ago – and your response is very helpful to my understanding of how to use it. Sort of a “sanity check” in my process.

I want to say the exact opposite: It’s better to have things that belong together (a project and its documentation) in the same repository. From my point of view it’s important that people don’t have to search for documentation in places that are separate from the code. Branches don’t have to be merged (or even share history), even though that’s the most common use case by far.

Note that you can also publish from a docs/ directory within a branch, see: Configuring a publishing source for your GitHub Pages site - GitHub Docs

I think that having a docs directory is a great way to do it; I was just remarking on the fact that branches weren’t meant to be separate “sub-repositories”.

I think that usually a repository with separate docs will link to it in the README or description. For most projects, an organization is created that has a docs repo and code repo so the docs are fairly close to the code.

Well, I found the information I need at About branches - GitHub Docs:

You can also use a branch to publish a GitHub Pages site. For more information, see “About GitHub Pages.”

This explicitly states that a branch can be used for something other than making changes to existing entities.

I really have been reading the documentation, but there’s a lot of information to digest. Slowly, but surely, I’m getting a good picture of the system.

I very much appreciate the comments that others have made.

1 Like

Key word here is “can”. Obviously it’s your choice. I think the size of the project also influences whether to have a branch, or a separate repo.