Github Pages – Free Hosting8 min read

Github Pages – Free Hosting

Github Pages – Free Hosting Tutorial

The super awesome GitHub service allows you to host as many free static websites as you want. All you need to do is host your code on GitHub repo! In this post I will be describing two methods to host your static site for free.

If are not aware of what GitHub & Git are, how to set them up, you can refer to this post. I will be using the same myNodeApp repo for this tutorial too. You can do the below steps with any GitHub repo.


Method 1 – Automatic Page Generators

Lets Navigate to the repo folder, click on the setting link on the bottom right hand side. This will take us to the settings page. Now, 3/4th down the settings page, you should see a section like this

Screen Shot 2014-02-28 at 9.28.44 AM

Click on Automatic Page Generator button.

PS: If you already have GitHub pages for the current repo, this will override those files & merge the changes. You can still access the old files via History of that file.

Now, you will find a form with a Project Name, Tag line, a Huge text area for our Mark down & a placeholder for Google Analytics Tracking ID. If you are new to Mark Down way of building a page, I would suggest you to use this editor. You can read more about Mark Down here.

Now, lets leave everything as is & click on Continue to Layout. There are quite a few themes listed on this page. You can play around and see which theme suits your needs. Then click on Publish (just below themes list). Booom!!! your site is ready!!

Now, you can access your site with this link format

http://<<user name>><<repo name>>

Very very very important. If your site does not show up & throws a 404 I would advise you to go for a smoke & get back after 30mins. Do not panic! 

Updating Files

Now your site is up & running but you want to change the content, styles etc. So, this is how you go about it. All the static pages that GitHub hosts are available on gh-pages branch. Back to the repo & click on the branch selector

Screen Shot 2014-02-28 at 9.43.32 AM

And select gh-pages branch. This is where the html code resides. Depending on the theme you have selected, you will see a list of files.

You SHOULD clone these files to your local & then make changes. Then commit these changes back to the remote repo (more details here).

Method 2 – Building from scratch(ish)

In this method, we are going to build a Responsive website from (kind of) scratch using Bootstrap. Then we are going to use our best friend – Git command line tools to create a new branch named gh-pages and push our changes.

Lets head here & pick this template. You can resize the page to check the responsive nature. Now, to download the template click here. Then select Download Source under Source Code section. Unzip the downloaded file to your favorite location & open up the folder. You will see a bunch of files. Don’t be scared, we are going to keep things as simple as possible.

Create another folder (anywhere else) and name it myStaticSite. Then create another folder inside & name it dev. Then, navigate inside the downloaded & Unzipped Bootstrap source folder. Then docs > examples. There you will see a folder named offcanvas. Copy the contents of this folder and paste it inside myStaticSite/dev.

Next back to the downloaded folder, copy the contents of dist folder and paste it inside myStaticSite/dev folder. Your myStaticSite/dev folder should look something like this

Screen Shot 2014-02-28 at 10.13.07 AM

Lets clean up by moving offcanvas.js to the js folder and offcanvas.css to the css folder. Next we need to update the references to the files inside index.html.

  • 1. Remove line no. 9 – link to favicon
  • 2. Update line no. 14 from
    <link href="../../dist/css/bootstrap.min.css" rel="stylesheet"> to  <link href="css/bootstrap.min.css" rel="stylesheet">
  • 3. Update line no. 17 from  <link href="offcanvas.css" rel="stylesheet"> to  <link href="css/offcanvas.css" rel="stylesheet">
  • 4. Remove lines 19,20. A debugging js file for IE8.
  • 5. Bottom of the page, Update line 124 from  <script src="../../dist/js/bootstrap.min.js"></script> to  <script src="js/bootstrap.min.js"></script>
  • 6. Line125 from  <script src="offcanvas.js"></script> to  <script src="js/offcanvas.js"></script>

You final index.html should look like this

Save the file and launch it in a browser. Hit F12 & you should not see any reference errors on the page. Resize the page to test its responsive nature.

Awesome!! now everything looks fine. Lets connect to GitHub, get the remote repo & update the files.

Back to myStaticSite create a new folder named remote-repo. Open Terminal/Git Bash here. Now we will first clone the repo. Navigate to your repo & get the git URL from bottom righthand side. Run

git clone

A new folder with your repo name will be created here. Lets CD inside that folder. Then run  git branch -a to see all the branches. If you already have a gh-pages branch, you can run  git checkout gh-pages. Else you can create one by running  git checkout -b gh-pages. I am continuing from the above method, so I will have a gh-pages already created.

Now, lets clean up this folder. Run this command even though you have created a new branch.   git rm -rf .

Copy the files from myStaticSite/dev to myStaticSite/remote-repo/myNodeApp (myNodeApp is the name of my repo). Then run git status, which will list all the added and removed files. Then lets stage the changes by running  git add . the commit the files by running  git commit -m "My Responsive Site". Next lets push these changes to the remote branch. Run  git push origin gh-pages, after you have provided your GitHub credentials, the branch should be updated.

Open a browser and fire away to

http://<<user name>>.io/<<repo name>>

PS : If your site dosen’t show up right away, wait for a few (~30) more minutes.

Thats it!! now you know how to use GitHub to host your static sites. 

Cheat sheet

  • Clone the repo : git clone<<user name>>/<<repo name>>.git
  • cd <<repo name>>
  • Create a orphan branch git checkout -b gh-pages
  • Clean the orphan branch git rm -rf .
  • Add a new file or create a new file echo "My GitHub Page" > index.html
  • Stage the changes  git add .
  • Commit the changes  git commit -m "First pages commit"
  • Push the changes  git push origin gh-pages
  • Launch  http://<<user name>>.io/<<repo name>>

More info here

Please do not abuse the free resources. If you are not intending to use a file, delete it from the repo.

Thanks for reading! Do comment.