GitHub Pages

GitHug Pages #

GitHug Pages is a static file hosting offering from GitHub to host content directly out of a GitHug Repository.

Pages is free for public repos with GitHub Free.

By default, GitHub Pages are hosted at <user><repository>.

Configuration #

GitHub Pages must be enabled in your Repository Settings page. Visit Settings > Options > GitHug Pages.

Select a source branch to build github pages. It can either build from the branch root / or the /docs directory. Only these two roots are usable. If you need to build your docs from another path consider using a GitHub Action to push that directory onto another branch to build from the root of that branch.

Convention disctates the branch to build GitHub Pages from be gh-pages, but any branch can be specified.

Custom Domain #

GitHub Pages can be hosted from a Custom Domain (i.e.

Purchase a custom domain name from a registrar such as Google Domains.

Point that Domain to <user> and add a CNAME file to the root of your pages branch which contains your domain.

See blog post for details.

User Pages #

There is an optional side benefit for creating a User GitHub Pages site with a custom domain name.

If you create a special repository called <user>, this will be a User GitHub Pages site. It will be hosted at <user> directly, instead of <user><user>

Specifying a CNAME in this repository will autimatically apply to all other GitHub Pages hosting of all other GitHub repositories you own.

For example:

  • Specify a CNAME of for <user>
  • Then another project hosted on GitHub pages will be accessible at<repository> instead of <user><repository>.