How to Publish a Github Page
Github Pages allow developers to host a static website of their project for free. It is one of Github’s key facilities that has made maintaining free open source projects more economical especially for indie developers.
Bootstrap and Normalize.css are a couple of popular Github pages. To create one, you only need to create a new branch of your project repository, and call it gh-pages
. Publish the branch to Github.
Once it is up, the site is accessible via the URL which is set relative to your Github username as well as the repository name. {username}.github.io/{repository-name}
.
Read Also: How to Create a Github Page for Your Project
You can setup a custom domain for your Github page. We have shown it how to do so in our previous tutorial.
Github Pages Simplified
Creating a Github Page is easy and quick. But, there is a small caveat.
Take one of the demo repositories in our Github account, Advent Calendar, for example. We have two branches — master
and gh-pages
which share the exact same of code branches.
We need to make sure that the codes in gh-pages
are always synchronized with the master
branch.
Fortunately, Github has recently made it simpler by removing the gh-pages
branch requirement. We can now instead feed the site directly through the master
branch.
To do so, go to any of your Github repository Settings screen. Scroll down to the Github Pages section and select the master branch menu from the selection.
You are all set and can safely remove the gh-pages
branch from the repository.
Serving Documentation
Some projects such as Bootstrap, Foundation, or Skeleton require a documentation page. And their developers usually also serve these documentation pages through the gh-pages
document.
So the repository now has two branches with a completely different set of codes and purpose; one is the main source, while the other one host documentations and also some code snippets. In this situation, you may often find change conflicts when switching between these two branches.
With this new change from Github, developers are now able to serve documentation pages through a folder name /docs/
within the master
branch. Then, go to the Github Pages and select the next option, master branch /docs folder.
Now, maintaining the source code and documentation has become more stremalined.