GitHub Pages is a GitHub service that will host your static website files, if you push them to a specific git repo or branch. This is one of the easiest ways for git users to host static HTML, CSS, and JS files.
This makes a perfect pair with a static site generator. In this article I outline a method to keep your entire static site project in one git repository.
How Github Pages Works
Github Pages has two types of repositories. A User/Organization Pages repository must be named
username.github.io. This project will publish the contents of branch
master as a static site. Create a git repository in the output directory and
git push origin master to deploy your site.
A Project Pages repository is more flexible. In this type, the static site is published from the branch
gh-pages. This leaves
master free for the code of a software project. In our case we will store the source files of our website in
Using the method below, we can keep the source and output in separate branches, while maintaining the default folder structure of our project.
Setting Up The Project
Every static site generator will use a specific folder structure, with the generated output usually in one subdirectory. We want our branch
gh-pages to be at the root of the output subdirectory. Our
master branch will be one level up, at the root of the entire project. We can use
.gitignore to nest one instance of the repository within the other.
Here is a step-by-step process to set this up:
- Create a local project using your site generator of choice
git inita repository inside the project and push to a remote repository on GitHub
Create or edit your
.gitignorefile and add the output directory of your project to the ignore list.
At this point, change and build your site. Do a
git status. You should only see changes to the source files, and not for the output folder.
- Go ahead and delete that output folder
Now clone your project from Github, into the place where the output folder just was. Rename it to match the original folder name. You can do this all at once using:
git clone <git-url> <folder-name>
Now we have have two copies of the repo, one nested inside the other. The outer source repo is blissfully ignorant of the inner one thanks to
- Move into the inner repository. It should contain a copy of the project source which we now want to remove.
- Create the new branch:
git checkout -b gh-pages
- Make sure the current branch is
gh-pages. Then use
git rmto remove the entire contents of the folder.
- Build your site. The inner gh-pages repository should now contain the build output from your generator (the static website).
git addthe files,
git commit, and finally
git push origin gh-pages.
Your site should now be published on Github Pages.
- For the outer repository, you will commit and push to
masterany changes to the source files.
- Commit and push to
gh-pagesfrom within the output subdirectory.