January 10th, 2016 By Marcia Ramos

How to publish Project Websites on GitHub

How to create a project website on GitHub

Quick overview: User/Organization Website vs Project Website

When hosting your website on GitHub (it’s FREE!) you’ll find two primary possibilities:

Create an User or Organization website - which can be accessed via http://username.github.io or via your own custom domain, like http://mydomain.com.
Create a Project Website - which can be accessed via http://username.github.io/projectname or via your custom domain or subdomain.

Note: If you are new to GitHub Pages and need a full overview on this subject, or if you are looking for a tutorial for publishing user/organization websites, you might want to check this article out first: How to publish your website on GitHub.

GitHub permits ONLY ONE USER/ORG WEBSITE per account but your are allowed AS MANY PROJECT WEBSITES as you want per GitHub account!

Deciding between the options 1 and 2 above

You might ask yourself: where should I get started then?

The answer is: from the beginning! Just kidding ! Well, usually we start from the first option, creating an user/org website. So you’ll have our main website at this domain name: username.github.io and then, if you need another website, you go for the second option, as it probably will be something like a subdomain of your main domain. But this is not required, specially if you intend to use them with your own domain name. You can start by creating a project website to warm yourself up and then create a main user/org website. It’s entirely up to you.

A project website can also be useful when you want to customize a section of your website completely apart from you main website. For example, let’s suppose you have an user website designed for a presentation of yourself of your business. Then you have a blog and a gallery section. You can easily have your main website as an user/organization site and two project websites to each section, blog and gallery.

An other good use of this feature is having different websites, for completely different purposes, all hosted on GitHub with a single account.

Anyway, if you want dig a little more into this matter please read our article How to publish your website on GitHub, where we go step by step on each option and explain in details how to publish your user/organization website.

Setting your Project Website up

For publishing a project website you will need to follow a few steps. Watch this video or go through the step-by-step below.

Note about this video: by the time of this screencast we had already set up our user website on GitHub to redirecting to our custom subdomain name (ramosmd.virtuacreative.com.br). When creating the new project website, GitHub redirects automatically to this previously set domain. So instead of the default GitHub Pages url (username.github.io/projectname/), we had our project redirected to subdomain.domain.com/projectname (in this case, to ramosmd.virtuacreative.com.br/blog/).

Step by Step

If you don’t have an account on GitHub, create one. It’s free.
Log into your account and create a new public repository. Name it as your project. For example, if you want a blog, you might want to name the repository as blog.
At this point GitHub will show you your domain name, which will be username.github.io/blog or instead of blog, it will have whatever name you’d given to the repository.
Create a new branch called gh-pages and then delete the master branch automatically created by GitHub.
Create your home page (index.html) on GitHub platform itself or upload you website content from the root folder to gh-pages branch (via command line or GitHub Desktop application).
Wait a few minutes and access your new website from any web browser connected to the internet.
IT’S DONE!

Things you need to be aware of

GitHub Pages supports only static websites. It means that only html, css and javascrip are allowed. Dynamic server-side files are not supported, as php. Database connections are not allowed either, like MySQL or MySQLi.
GitHub Pages does supports CSS preprocessors like Sass and Scss files.
If you want a website written dynamically, we strongly advise you to try Jekyll or another Static Website Generator. Jekyll is awesome to deal with, easily handled, quick to learn and fully supported by GitHub Pages.
GitHub has not a maximum storage capacity for users. That means you can store as many files as you need and create as many project websites as you want! Awesome, isn’t it?!
A repository does have a storage limit of 1 GB, but you can create as many repos as you want.
All GitHub repositories are public for free users’ accounts. So we strongly recommend not uploading sensitive information to your repositories. By upgrading to premium accounts you’ll be allowed to create private repositories, but ALL repos created to hosting websites MUST be PUBLIC. (Updated in 03/30/2016)

About custom domain names

GitHub allows you to use custom domain names for both user/organization and project websites. You can configure as many domain names as you want when you have multiple websites. For example, if you are a web developer or a web designer, with only one GitHub account you can host unlimited numbers of websites, and you can configure a different domain or subdomain name to each website you have.

When you configure your user/organization website for a custom domain like mydomain.com, if you create project websites they will be automatically redirected to mydomain.com/projectname/. If you want to change this, it’s easily done by adding a CNAME file to your gh-pages branch (project website root), redirecting to another domain or subdomain you want.

If you need an overview for configuring your custom domain with GitHub Pages, stay tuned to Virtua Creative Blog! Our next article “How to add custom domain to your website hosted by GitHub” will fully cover this subject. Follow us on Twitter or subscribe to our YouTube Channel for updates!

References

Last update: 03/30/2016 - 20:47h.

How to publish Project Websites on GitHub