Showing results for 
Search instead for 
Did you mean: 
Copilot Lvl 2
Message 1 of 2

Understanding GitHub Pages deployment of generated documentation

I'd like to deploy my generated documentation files (primarily html) to GitHub Pages. I have an (open source) organization with multiple members and a few repositories at (and obviously


We have a large amount of annotated C++ code and are using Doxygen to generate HTML documentation from the source code. We are also using Travis for CI builds (and will also use GitHub actions in the future for our CI builds).


Since we are an organization we can't use the "gh-pages" branch for automatic deployment of the generated code. My understanding is that we can only use the "master" branch to render our GitHub pages at our .io address.


Question 1: I don't want to "git push" the many generated files to our master branch, at least in our source code repositories. Besides cluttering up git logs, it requires first deleting everything out of the documentation directory before pushing the new generated files back into the doc directory (or putting in place some sort of "diff between old and new set of generated files, delete unneeded old files, push new ones" script). Is there a better process?


Question 2: Related to 1, I'd be ok with pushing all generated files to our ".io" repository, which would keep our source code repositories clean of all generated doc files. It does complicate our documentation organization and the Doxygen generation step significantly, specially when putting it into some sort of deployment script (and we would still need the "diff" script). Is this what other organizations are doing?


Question 3: I've looked at third-party web sites that host documentation (such as Read the Docs at, but each one has some drawbacks. I would rather use GitHub Pages. Should I reconsider a third-party web site?


Question 4: Am I missing something obvious? Is there a way to deploy to GitHub Pages without actually "git push"ing to a branch somewhere? I understand the Jekyll static site generation process (at a very high level), but IIUC I still need to push the doc files before the Jekyll (or other static web site generation) process kicks in.


I'm generating nice documentation (through CMake and Doxygen) locally, so I know the documentation generation works well. I'd rather not have to upload these files every time we create a new release, though, and would much rather automate the process through GitHub (and Travis, as needed). I've been searching online for weeks, but still don't have the understanding or directions that I need (most of the online help is oriented towards "gh-pages" workflows).


I greatly appreciate any and all comments and help.




1 Reply
Copilot Lvl 2
Message 2 of 2

Re: Understanding GitHub Pages deployment of generated documentation

A follow-up and clarification - I was slightly confused, thinking that we couldn't use "gh-pages" branch at all. This is not the case. Each of our repositories that is not our organization named repository (i.e. all of our repositories that are not named "") can be configured to use "gh-pages" as the publishing source. Many of the online articles (outside of GitHub help) don't show the correct way to get to the "publishing source" option on the repository settings.


I'm still working through various possibilities, but we can definitely do the following: set the "gh-pages" branch to not store history, and remove all old generated files before generating a new set. This removes some of my main concerns about keeping a lot of history and removes / adds on the master branch.