A step-by-step explanation of how GitHub Pages work

GitHub Pages Flowchart.md

• Create a repository on GitHub.

• Make your very first push to the repository.

• Did you name your repository "username.github.io", where username is your GitHub username?

  • If yes, then on your very first push to the repository, GitHub Pages is automatically enabled to be built from the root directory of the default branch. You can read more about how the default branch is set here. Note that the default branch is determined according to the rules described in that link and that's the branch that GitHub Pages will build the web site from. Having a branch named gh-pages on your very first push does not matter. That is, even if you have a branch named gh-pages on your very first push, it will not be treated as a "special" branch. It will be treated just like any other branch. The default branch will be determined according to the rules explained in the link, and GitHub Pages will be build your web site from the root directory of the default branch. After your very first push, you can manually change the branch, or the directory, (or both) where GitHub Pages will build your web site from.

    Another thing to note is that not having a branch named gh-pages on the very first push, but adding it in later pushes does not make a difference either. That is, if you add a branch named gh-pages on the second or later pushes, it will not become the branch where GitHub Pages is building your website from. The branch determined as the default branch on the very first push will still be the branch where GitHub Pages is building your website from. The only way to change the branch where GitHub Pages is building your website from is to manually change it by navigating to the repository's page on GitHub, then changing the value of the "Branch" setting that is under "Settings -> Options -> GitHub Pages -> Source". Note that you can change the directory where GitHub Pages is building your website from in this section as well.

    One more thing to note is that changing the default branch manually on a repository does not change the branch where GitHub Pages is being built from. To change the branch where GitHub Pages is being built from, you have to change the value of the "Branch" setting that is under "Settings -> Options -> GitHub Pages -> Source" on the repository's GitHub page. This applies to both repositories that are named "username.github.io" (where username is your GitHub username) and other (regular, conventional) repositories.

  • If no, does your repository on GitHub contain a branch named gh-pages? The gh-pages branch doesn't have to be created on the very first push, it could have been created in later pushes as well.

    • If yes, then GitHub Pages has already been automatically enabled to be built from the root directory of the gh-pages branch. Note that when you delete the gh-pages branch on GitHub, GitHub Pages will be reverted to being disabled again.

    • If no, then GitHub Pages is disabled. You can enable it manually by going to "Settings -> Options -> GitHub Pages -> Source" on the repository's GitHub page, and then selecting a branch to build the GitHub Pages web site from. The directory under that branch to build the GitHub Pages web site from will be the root directory by default. You can change it to /docs, or leave it as root. There are no other options for the directory other than these two options.

    One thing to note here is that if your "regular" repository (a "regular" repository is a repository whose name is not "username.github.io", where username is your GitHub username) has a branch named gh-pages on GitHub, then GitHub Pages for that repository cannot be disabled until the gh-pages branch is deleted. That is, if your repository on GitHub contains a branch named gh-pages, then GitHub Pages for that repository stays enabled until the gh-pages branch is deleted. So, if you don't want to delete the gh-pages branch, you can configure GitHub Pages to build from another branch (instead of the gh-pages branch), but you cannot disable GitHub Pages for that repository until you delete the gh-pages branch on GitHub.

• After making sure that GitHub Pages is enabled and determining which branch GitHub Pages is configured to build your web site from, check if you have a file named .nojekyll under the "publishing source". The "publishing source" is the branch and the directory that you selected for GitHub Pages. For example, if GitHub Pages is configured to build your web site from the root directory of the branch, say baz, check if there is a file named .nojekyll under the root directory of the branch baz. If, on the other hand, GitHub Pages is configured to build your web site from the "docs" directory of the branch, say qux, check if there is a file named .nojekyll under the "docs" directory of the branch qux.

  • If there is, then at GitHub Pages will treat the contents of the "publishing source" as the already built, final assets. That is, on every push (to the branch that GitHub Pages configured to), GitHub Pages will do nothing but it will simply copy the files and directories under the "publishing source" directory recursively into its web server.

  • If there is not, then GitHub Pages will treat the contents of the "publishing source" as the source files which will be fed into Jekyll configuration on GitHub Pages servers. That is, if there is no file named .nojekyll under your "publishing source", then on every push (to the branch that GitHub Pages configured to), GitHub Pages will build the contents of the publishing source with Jekyll, using the Jekyll configuration of the GitHub Pages servers. After the build, it will copy the output of the Jekyll build into its web server.

  So, the only difference between having vs. not having a file named .nojekyll under the publishing source is how GitHub Pages treating your publishing source. If you have a file named .nojekyll under the publishing source, then GitHub Pages treats your publishing source as already built, ready to publish assets. Hence, it this case, all it does is it simply copies whatever under the publishing source onto its web servers. Whereas if you don't have a file named .nojekyll under the publishing source, then GitHub Pages treats your publishing source as the input to a build process. The build process is a Jekyll build that happens on GitHub's servers. That is, if you don't have a file named .nojekyll under the publishing source, then GitHub Pages takes whatever under the publishing source, passes them into the Jekyll build on the GitHub servers, gets the output from the Jekyll build and then copies this built output onto its web servers.

  Note that even if you have a file named .nojekyll under your publishing source, you can still use Jekyll. Having a file named .nojekyll under your publishing source and using Jekyll means "I want to use Jekyll but I want to control the whole build process of it, instead of sending my source (input) files to GitHub's servers and letting the build be performed there". This way, you will build your website using Jekyll on your own computer (or on another server), and then only send the built output to GitHub. "Sending the built output to GitHub" means committing the built files to the publishing source and pushing the branch to GitHub.

  If, on the other hand, you would like to:

  • Use Jekyll
  • Let GitHub Pages build your website, instead of building it locally and pushing the built, final files under your publishing source to GitHub.
  • But still would like to test the website locally to understand how it will look after GitHub Pages builds it on its servers.

  Then you can use a Ruby gem named github-pages. It is an open source gem which is hosted on GitHub, and the name of the repository on GitHub is pages-gem. The purpose of this gem is to replicate the Jekyll configuration and environment of GitHub Pages as closely as possible, so that you can replicate the GitHub Pages' Jekyll build process on your local development environment and hence, test your website locally. Technically, when you use this gem, you will still build your website locally (otherwise, how could you be able to test it locally?). However, you will only push the source files to GitHub Pages servers and let the GitHub Pages build them.

  My personal opinion is, unless there are some things that can be accomplished only by letting the GitHub Pages build your website (as opposed to building it locally and pushing the final assets to the publishing source), this is a pointless thing. GitHub could have easily made GitHub Pages without any build support on the servers, let people use anything they wanted to build their websites, and only accept the final, built assets under the publishing source. This way, there wouldn't be any extra load on GitHub Pages servers caused by the countless Jekyll builds initiated by countless users. Nor there would be a need for GitHub to develop and maintain a project like pages-gem, since people would have used whatever static-site generators out there, built their websites locally (or on another server) and only push the built, final files to GitHub, instead of pushing something that needs to be built on GitHub servers.