Github pages is a fantastic web hosting product for developers. The help document is just OK if you are going to setup a user(or organization)site. But if you want to setup a project site with it, the help document is not as good as the product itself. That's why I decide to write down the whole process of my setup.

This could be the ONLY issue free instruction you could find for project site setup.

Concept Of Sites

Github pages could be setup into two types:

• user/organization site
• project site

It depends on what content would be shown in the pages. If it's a show window of the user or organization brand, it is the first type. If it's a support site of a specific project, it is the second type.

Whatever the type you select, you need a place(a repo) to contain the sources of the site(HTML, CSS, JavaScript, images ... not the source of your project).

For the first type, you will need a new repo on github with the repo name like:

https://github.com/yourname/yourname.github.io

After setup, you will get a site:

https://yourname.github.io/

For the second type, the project repo will be used for site sources, but you won't like to mix them with project sources together. So an isolated directory or branch should be created just for site sources.

After setup the second type site, you will get:

https://yourname.github.io/yourproject

Any access outside this path, like https://yourname.github.io/ will get a 404.

As I said above, the instruction from Github help of user/organization site is just OK. We will focus on the second type in this article.

Ruby & Jekyll

Github Pages is a static content hosting service. It works well with a bunch of static page generators like Jekyll, Hugo ... etc.

Jekyll is the recommended solution by Github Pages team, we will have Jekyll in this instruction as well.

Jekyll is written in Ruby which I don't know much about it. You could skip this part if you are Ruby developer. This part is for developers like me who don't know Ruby at all.

It's very important to follow the steps below because Github Pages documents don't have any instructions of installing Ruby. If you refer to Ruby or Jekyll documents, you will have latest version installed but not match with Github Pages, which cause endless issues later.

Install rbenv which is used to manage Ruby runtime versions, like nvm for Node.js.

brew install rbenv

If you are running OS rather than macOS, install rbenv from your favorite package manager(apt or rpm whatever depends on your OS).

Then add the following line into your .zshrc:

eval "$(rbenv init -)"

It will help setup your Ruby environment variables. After relaunch your terminal, now we could install Ruby now:

rbenv install 2.7.1
rbenv global 2.7.1

Install Jekyll:

gem install bundler
gem install jekyll -v 3.8.5

To specify the version is very important, you need a local Jekyll has the exact same version as Github Pages. The version may change, check Github Pages Help for update.

Setup Local Repo

The local repo is used for your project site sources(HTML, CSS, JavaScripts, markdowns, etc). We will create a branch of your project for it in this instruction.

We will create an orphan branch from an empty directory to make sure the site sources are isolated from project sources and no dependencies with each other.

git init yourproject
cd yourproject
git checkout --orphan gh-pages

'yourproject' is the repo name of which you want to setup site for.

Populate site with Jekyll

We are working on 'gh-pages' branch of 'yourproject'. Jekyll is introduced now to populate a template website. We will focus on how Jekyll works, instead of how to add new content to the template site in this step.

run Jekyll:

jekyll _3.8.5_ new .

Github Pages help document tells me put VERSION after 'jekyll' in the command, but I don't know add the underscores around the VERSION because I'm not Ruby developer. It took me a lot time to figure out the problem.

Also the help document said you could run 'bundle exec ...', but actually you will get 'No Gemfile found' error if you do that. Just run jekyll directly because it's already in your PATH set by rbenv.

There would be some files and directories generated after above command executed.

Add the following line to Gemfile:

gem "github-pages", "~> 204", group: :jekyll_plugins

204 is the version specified by Github Page dependencies. Check the exact version you need from the help document.

Change 'baseurl' in _config.yml:

baseurl: "/yourproject"

This step is crucial for project sites, baseurl must be specified correctly otherwise you would loss all the CSS file accesses.

Now, try to get all dependencies:

rm Gemfile.lock
bundle

Remember to delete Gemfile.lock first, so that you could get the right dependencies(As we manually added github-pages? maybe).

Test Locally

You must always want to know what the site looks like before publish it to internet.

bundle exec jekyll serve

If you run 'jekyll serve' without bundle, an i18n dependency error will be reported. I don't know why this happen(it seems some magic in Ruby dependencies) and don't want to make it work as all the above steps drive me crazy already.

Open the following URL in your browser:

http://127.0.0.1:4000/yourproject/

You will see:

Commit To Github

You are working on gh-pages branch locally by now.

.gitignore file was created already by Jekyll, just add all and commit:

git add --all
git commit

Github Pages help document does not mention this step and I also forget it for my first try.

Now push the branch to Github:

git remote add origin https://github.com/yourname/yourproject.git
git push -u origin gh-pages

Once after your gh-pages branched pushed to Github, your site could be accessed in few minutes via URL:

https://yourname.github.io/yourproject

You will see exactly what you see as in your local testing.

Additional Bonus(subdomain from js.org)

If it's a JavaScript project, I strongly suggest you apply a subdomain from js.org for your project. So that you could access your project via:

https://yourproject.js.org

It is shorter and looks much attractive than yourname.github.io/yourproject.

Subdomain of js.org is free for apply. Just follow the simple 4 steps shown on js.org.

• make sure you have meaningful content in your site already
• pickup a subdomain you like
• add CNAME file in your repo
• pull request to add your subdomain to "cnames_active.js"

The new domain name would take up to 24 hours to go live. There would come out another issue after that.

Remember that we set baseurl to "/yourproject" in _config.yml? Set it back to "" because we don't have a baseurl now.

A live example could be found:

• github repo
• httpunit on js.org

Recap

If you are trying to setup Github Pages for your project instead of for you personally, DO NOT follow the steps on Github Pages help document. Follow this instruction would save at least 5 hours for Non-Ruby developers.

Good luck!