Hosting in GitHub Pages

Basics

The GitHub repository must be public in order to use GitHub Pages with a free GitHub account.

The root of a GitHub Pages site must come from either the root of the repository or a "docs" folder within the root. In this case, I named the directory containing the site files "docs" and configured GitHub Pages to use the "docs" folder as the root.

Aligning the URL path in development

The default URL for a site hosted on GitHub Pages looks something like this: https://account_name.github.io/repository_name/page.html. In this case, if the docs folder is used as the root, page.html would be located directly within the docs folder of the repository. In order for root-relative links to work as expected in development (that is, outside of GitHub Pages), the repository_name part of the path must be included.

One way to do this is to create a directory in development that is a sibling to the docs directory and exclude it from git. Then within that directory, create a symlink to the docs directory having a name matching the repository name. Starting a simple development web server (such as python -m http.server) in the docs directory should result in URL paths that are consistent with those in GitHub Pages. This works well for development in the Google Cloud Shell, for example.

Cache-Control

GitHub Pages appears to send responses with the HTTP header cache-control: max-age=600. This ensures that the browser goes back to the server for a new file if the file was last retrieved more than 10 minutes ago.