User or Organization site

In Hello GitHub Pages I wrote about creating a Github Pages User site to host www.tracktownsoftware.com.

GitHub allows one GitHub Pages User or Organization site per account. This special GitHub repository must be named in the form username.github.io where username is your username (or organization name) on GitHub.

On GitHub.com your source code for this site will be the familiar GitHub repository path https://github.com/username/username.github.io.

What does it mean to be a GitHub Pages site? In a browser when you navigate to https://username.github.io then GitHub will try to present the contents of this repository as a static website.

Project Site

Your other repositories (not named username.github.io) can be set up to include a GitHub Pages Project site.

On GitHub let’s say you have a repository containing source code at https://github.com/username/mygreatlibrary where username is your username (or organization name) on GitHub.

You can publish documentation about mygreatlibrary in the same repository.

  • The default publishing source for a GitHub Pages Project site is the root of the gh-pages branch. You will have to add a gh-pages branch to the mygreatlibrary repository and add your markdown or html/javascript/css documentation files there.
  • You can alternatively add a folder named “docs” (or any name) to the mygreatlibrary repository main or master branch to hold your documentation files. To designate this folder for your GitHub Pages Project site (Github describes this as choosing a publishing source) go to the repository settings and scroll down to Github Pages Source and select the “docs” folder from the branch where you put it.

You can see your mygreatlibrary Github Pages Project site in a browser by navigating to https://username.github.io/mygreatlibrary.

Managing a custom domain for your Github Pages sites

Your default subdomain for all your Github Pages sites is username.github.io.

You can use your own custom domain by following these DNS CNAME record instructions from Github: Managing a custom domain for your GitHub Pages site

After following the above instructions for my tracktownsoftware.github.io repository I can now navigate to https://www.tracktownsoftware.com rather than https://tracktownsoftware.github.io.

A byproduct of a custom domain for username.github.io is it also affects the path to Project sites. For the mygreatlibrary example I can now use https://www.tracktownsoftware.com/mygreatlibrary rather than https://tracktownsoftware.github.io/mygreatlibrary. You still have the option to set up a custom domain, such as www.mygreatlibrary.com, in the mygreatlibrary repository by following GitHub’s custom domain instructions.

Helpful links