A Static Site Folder Structure for Github Pages

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 master.

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:

1. Create a local project using your site generator of choice
2. git init a repository inside the project and push to a remote repository on GitHub

3. Create or edit your .gitignore file 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.

4. Go ahead and delete that output folder

5. 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 .gitignore.

6. Move into the inner repository. It should contain a copy of the project source which we now want to remove.
7. Create the new branch: git checkout -b gh-pages
8. Make sure the current branch is gh-pages. Then use git rm to remove the entire contents of the folder.
9. Build your site. The inner gh-pages repository should now contain the build output from your generator (the static website).

10. git add the files, git commit, and finally git push origin gh-pages.

    Your site should now be published on Github Pages.

11. For the outer repository, you will commit and push to master any changes to the source files.
12. Commit and push to gh-pages from within the output subdirectory.