GitHub Pages: User or Organization versus Project sites

2020-12-22T18:20:00+00:00

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

Hello Github Pages

2020-12-17T21:51:59+00:00

Moving my website to GitHub Pages

Going into 2021 I decided to become more active on GitHub and try my hand at a programming blog. Before GitHub Pages I hosted my website on DiscountASP.NET. I began implementing my blog in ASP.NET but then decided it will be simpler to host it on a GitHub Pages user site with the Jekyll static site generator.

There’s a lot of information online for making your own GitHub Pages blog with Jekyll, so I won’t document the steps here. This post on kiltandcode.com steps you through the entire process. See my list of helpful links below.

The one issue I ran into: Jekyll required installing Ruby onto my Windows 10 computer. RubyInstaller ver 2.7 didn’t seem to install correctly, so I uninstalled it and found success with RubyInstaller ver 2.6.

Custom Domain for my Github Pages site

I needed subdomain www.tracktownsoftware.com and apex domain tracktownsoftware.com to point to my new Github Pages site. Github explains how to Manage a custom domain for your GitHub Pages site.

The subdomain was easy. On DiscountASP.NET I added a DNS CNAME record to point www.tracktownsoftware.com to tracktownsoftware.github.io (my Github Pages repository).

The DiscountASP.NET DNS Manager doesn’t support ALIAS, ANAME or A records, so tracktownsoftware.com still pointed to my old site. My solution was to do a redirect by making an empty “ASP.NET Web application (.NET Framework)” in VS2019 and then adding the index.html below. I deleted the existing files on DiscountASP.NET and then published my simple redirect web application.

<html>
<head>
    <meta charset="utf-8" />
    <meta http-equiv="refresh" content="0; URL='https://www.tracktownsoftware.com'" />
    <title>Redirect to new www.TrackTownSoftware.com...</title>
</head>
<body>
</body>
</html>

Development environment for my Github Pages site

I use Visual Studio Code to open and edit the project folder in my Git local repository. VSCode supports Git actions by clicking on icons in the project Explorer window, but I prefer typing Git commands into a VSCode terminal Bash window.

In the VSCode terminal Bash window you can test your Jekyll website by running the command below. It will respond with a local server address you can click on. In VSCode you can make edits to your site, save and then refresh your browser window to see changes.

$ jekyll serve

If the above command doesn’t work try using:

$ bundle exec jekyll serve

Track Town Software

GitHub Pages: User or Organization versus Project sites

User or Organization site

Project Site

Managing a custom domain for your Github Pages sites

Helpful links

Hello Github Pages

Moving my website to GitHub Pages

Custom Domain for my Github Pages site

Development environment for my Github Pages site

Helpful links