An Introduction to Web Hosting with GitHub Pages

In your travels around The Internet you may have encountered sites with URLs ending in .github.io. These use GitHub's own minimalist but very useful hosting service called GitHub Pages which is available free to anyone with a Github account.

In this article I'll show how easy it is to get up and running with the service, as well as exploring what you can and cannot do.

"Minimalist but Very Useful Hosting Service"

What you get with GitHub Pages is hosting for static files. That's it! You can't get more minimalist than that. If you need any sort of server-side stuff like PHP, a CMS or a web service then GitHub Pages isn't for you.

If you just need a few pages of text and images about you and your projects then GitHub Pages is ideal. However, static files don't limit you to static sites because those files can include JavaScript, making it possible to host web applications of any complexity. Furthermore, GitHub Pages integrates with the static site generator Jekyll which I'll cover in a separate article, and as the final bit of icing on the cake you can even use your own domain name.

Just Push to a Repository

The minimum you need do to get up and running is push an HTML file called index.html to a repository with the same name as your GitHub username. Of course you will probably also want to add a few more files such as images and CSS, and maybe even JavaScript files. Your content is then live at [username].github.io. (Note the TLD is .io, NOT .com.)

You can also create further index.html* files in your other repositories, enabling you to create an extensive site to showcase all of your work. These are known as project sites and have the URL format [username].github.io/[repositoryname]/.

(* Web servers like Apache and IIS allow you to specify the default page, and usually have a few pre-configured. With GitHub Pages you are restricted to index.html.)

Creating a User or Organization Site

If you are experienced with Git and GitHub you probably by now have most of the information you need to get something hosted on GitHub Pages but I'll go through all the steps in detail.

I have a few web applications which I would like to host on GitHub Pages so to demonstrate the process I'll create a GitHub repository with my username, CodeDrome, for the home page and a few other repositories for the individual web apps, each with their own index.html file.

The main page consists of the following three files which we'll push to Github:

• index.html
• banner.png
• styles.css

Firstly you'll need to create your index.html file and any other associated images, CSS files etc., ideally in their own folder. Then on the command line navigate to the folder and create a local Git repository with this command:

git init

Then add the files:

git add index.html banner.png styles.css

And finally commit them:

git commit -m "First version of home page"

Then log in to GitHub, click the + sign at the top right of the screen and click "New repository".

Type in your user name suffixed with .github.io as the repository name, and click "Create Repository".

This will take you to the repository page with various instructions on what to do next. I'm pushing an existing repository so I need to go back to the terminal and run the following:

git remote add origin https://github.com/CodeDrome/CodeDrome.git
git branch -M main
git push -u origin main

On the last command you'll be prompted to enter your username and password, and after a few moments you'll see something like this:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 4 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 5.49 KiB | 5.49 MiB/s, done.
Total 5 (delta 0), reused 0 (delta 0)
To https://github.com/CodeDrome/codedrome.github.io.git
* [new branch] main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

That's all there is to it. Your index.html page and any other files are now available for the world to see at [yourusername].github.io, and any time you need to change your site just edit the files and push them to GitHub.

Creating Project Sites

There can be only one user or organization site because its repository name is your user name, but as I mentioned you can add an index.html file to any or all of your other repositories and enable GitHub Pages on them. Pushing files to other repositories is of course done in the same way, but you also need to enable and configure GitHub Pages for each additional repository.

To do this click on Settings (the gearwheel icon).

Scroll down to GitHub Pages and click the link to the dedicated tab.

You can now select the Branch and directory to use.

Your repository page is now at [username].github.io/[repositoryname]/ and again you just need to edit and push files when you want to update the content.

There's Some Really Interesting Stuff Out There

Github Pages are typically used by software developers to showcase some of the more innovative and imaginative projects they are working on so there is a lot of really interesting stuff to be found on github.io. I have started to collate a list of my favourites which will form the basis of a future article, and as I mentioned earlier I am also working on an article on the Jekyll static site generator.