Building a Site with GitHub pages

Introduction

Github allows users (even Free users) to host publically facing websites. This can be very useful to host the documentation of a given tool or create a personal website. This very website uses Github pages.

By default pages are hosted at www.XXXX.github.io but if you buy a domain name it is also possible to use that.

The Documentation is excellent and should allow any user to get their site up and running. If you don’t understand soemthing in this tutorial please refer to the official documentation.

Github Pages can host static websites (written in HTML) BUT using tools like Jekyll makes blogging simple by applying templates allowing the end user to write in markdown AND NOT HTML. See GitHub + Jekyll Docs

Other tools like wowchemy and Hugo also exist

Tips

• When using github pages in a larger project (not just for a personal website) it is a good idea to have a branch called gh-pages that holds the documentation and launches the site of from this. When using it as a personal website using the main branch is fine.
• You can choose from a list of themes to get started:
  • Official Themes These are easiest to start with
  • Jekyll Themes on Github
  • Jeykll Themes on website
  • Hugo Themes
  • wowchemy Themes

Instructions

Activating Github Pages on a Website

To create a personal / organisation website make sure to use (USERNAME_OR_ORGANISATION_NAME.github.io).

1. On the repository pages click settings (up the top)
2. In settings click pages (near the bottom on the left)
3. Choose branch and directory (leave this as main and root for a personal page but maybe something like gh-pages and docs for documentation, you will need to create them first)
4. Click save

wowchemy

Documentation

Github pages

Documentation