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.