How to Host a Project Demo for Free on Github

Since the beginning of my coaching sessions to help junior web developers land their first job, I've gone through quite a number of Github profiles.

Setting aside the obvious difference in project complexity, I noticed two major differences that greatly affect how a profile is perceived:

• The writing quality of README.md files
• The absence of a demo link to test the project online (when possible)

I won't talk about the readme here since it's the subject of another article on the blog, but I'll explain how to easily host a project's demo (or documentation) on Github.

How to do it

Note that only static files are hosted by github.io, don't expect to host a php or java site on it!

Preparing your project

The first step is to commit a build version of your project to the repository. For example, we'll decide to add the "dist" folder, while remembering to rebuild the project before pushing a new version.

Example of a project organization containing a demo

Once a static version of your project is available in one of the repo's folders (or at the root for the simplest web projects), we'll configure the github repo.

Configuring the Github repo

To enable hosting, simply open your project's Github page and click on the "Settings" tab in the top right.

Once the options are displayed, scroll down to the "Github Pages" section as shown in the screenshot below.

Normally the source will be set to "None" by default, you just need to select "master branch" and your Github repo will be hosted on github.io!

Testing

All that's left is to click on the link that appeared directly on the section as shown above, and you'll be able to view your project.

Note that if you decided to put the static version of your project in a subfolder, you'll need to add the folder name to the provided url. For my example, the hosted version of the project can be found at the url: https://nicolasbrondin.github.io/cookie-consent/test/

And that's it, we're done!

Remember to add a demo of your project on github.io whenever possible (and if the code isn't hosted elsewhere), it's a real plus for curious developers who want to see what the project looks like and be able to play with it!

As a bonus

Github even offers the possibility of linking a custom domain name to the hosting, as explained in their documentation linked below:

https://help.github.com/en/github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site