GitHub Pages
There are a wealth of tools and services available on the Internet that can be used to build and serve web sites completely for free. Although free, they usually have limitations in use, but those limitations are usually more than sufficient for personal use.
In this example, we will create a simple web page using HTML, CSS, and JavaScript. We will show how we can use the GitHub Pages service to save and serve HTML, image and other files, how to use the Google Firebase Realtime Database as a database, and how to use the Bootstrap CSS framework to quickly customize the page layout.
What is Git (Hub)
If you are a developer, you probably use or have at least heard about GitHub.com. Let’s briefly explain what this service allows. To make it easier to understand GitHub.com, consider the first part in the name of this service: Git.
Git is a versioning system created by Linus Torvalds (the man who created Linux). Developers often use it to version programming code. When developing an application, developers often make changes to the application code. By using the Git tool, all changes can be preserved as a specific version of the program code that is stored in the central repository. All program code versions are visible and available and the programmer can return to any version at any time. Also, code versioning makes it easier to collaborate when multiple developers are working on the same project. Every developer can work on his task, in his part of the program code. When they are ready, they can push the changes they made to the central repository. After that, other developers can pull those changes. If multiple developers have made changes to the same line of code, Git will recognize that and report the conflict which needs to be resolved. This will ensure that one developer does not overwrite the code of another developer.
At the beginning we mentioned that the Git system was used for versioning, but we did not explicitly say what. Although programmers often use it to version code, Git can be used to version, well, any files. For example, if we need to keep various versions of Word, Excel, images, videos, or any other file, we can do this with a Git system. Git is not the only versioning system available, but at the time of writing this article is the most popular. Other versioning systems are Subversion, CVS, Mercurial, and others.
An important thing to understand is that Git works locally. Git is in principle an application that we install on a computer and we usually use it from the command line. After we install it, we can start versioning our files that are located in some directory. Git will create a repository from our files. The repository is a whole that contains all the files we’ve included in the versioning. So this can be a project, an application, an application plugin, several files, or simply one file. But our repository will only be saved on our local computer. If we want to share our repository with others, we need to use a server that understands Git. At the time of writing this article, one of the most popular online services that allows free Git repository storage and sharing with the world is GitHub.com.
Git Repository as a Web Site
GitHub.com offers great tools to save, update, share and generally track Git repositories. Along with the basic tools for versioning, GitHub.com also offers the ability to serve web pages from the repositories themselves. This service is called GitHub Pages. In this article, we will deal exclusively with the creation of web pages on the GitHub Pages service.
GitHub Pages allows you to create an unlimited number of web pages, but only one web site may be linked to our account name at GitHub.com. Other sites can be linked to the unlimited number of repositories we have on GitHub.com. By default, each web page will receive a free domain of ‘http://accountname.github.io’ (for a web page linked to the account name) or a domain ‘http://accountname.github.io/repositoryname‘ (for a network page linked to the repository name), but there is a possibility to define custom, proprietary domains on each web page.
The interesting thing is that the entire process of creating a web site can be done through the GitHub.com interface. We do not need to know any Git command and we do not have to save anything locally. Of course, if you know how to use Git, the thing becomes even simpler because the repository, that is our network page, can be edited on a local computer where we have a (better) text editor. In this article we will use only the tools available on the GitHub.com interface and in general on the Internet, so let’s get going.
Creating a Repository
The first thing we have to do is go to https://github.com and sign up with our account. If we do not have an account, we need to create it. The next step is to create a repository, which can be done at https://github.com/new.
As mentioned, we can create a web page that is linked to the account name or to a particular repository. We will create a web page linked to the account name. In order to do so, the name of the repository we create must be in the form of ‘accountname.github.io’, where ‘accountname’ is the name of the user account we use at GitHub.com. In our case, the name of the repository will be ‘cicnavi.github.io’, and your repository name will be different. With the name of the repository we will also provide a description of the repository (this item is optional), choose that our repository is public (because private repositories are paid), select ‘Initialize this repository with a README’ (README file will be created which can be used to describe our repository in more detail), and specify the license (MIT in our case). The whole thing now looks like this:
When we click on the ‘Create repository’ button we will see our new repository. Our repository now contains LICENCE and README files, and we can continue to add our files. So, at this point we’re starting to make a web site. Our web site will be static for now, meaning that it will only display the content that we define in the files themselves. In order for the GitHub Pages server to serve the network pages, there must be one file named ‘index.html’. If we have an existing file we can upload it with the ‘Upload file’ button. We will create a new file, directly in the interface, via the ‘Create new file’ button (marked in yellow).
Editing files
For the file name we will enter ‘index.html’. Furthermore, since it is a web page, the content of the file ‘index.html’ must be properly formatted HTML content. For start we will only have the basic HTML5 skeleton (the code is available at: https://gist.github.com/cicnavi/27c70bb99f9f67e97f115e80779de98d).
The content we have entered must be saved. At the foot of the file editing page, we will see a section to save the file with the title ‘Commit new file’. The word ‘Commit’ will often be seen in the Git world, and is related to saving all the changes that have been made to the files in the repository. In this case, ‘Commit new file’ can be understood as saving a new file and its contents in the repository. We need to give a description of what we did and select the branch in which we want to save the changes. Branching in versioning is a concept that we do not need to worry at this time, so we will only select the master branch.
After clicking the ‘Commit new file’ button, we’ll see that our new file is saved in the repository.
After we make changes to the file, our web site will be available on the Internet in a few minutes. In our case, the address is https://cicnavi.github.io/, according to the name of the repository we have created. If we open that address in our browser, we’ll see ‘Hello World’ (the text we’ve entered in the <h1> HTML tag in the ‘index.html’ file).
If we look at the source page, we can see the entire contents of the ‘index.html’ file (right click on the page> View page source).
CSS styles
The next step might be adding CSS styles that we will use for formatting. Fortunately, there are already finished HTML, CSS and JavaScript frameworks, free to use. One of the more popular one is Bootstrap, and its inclusion on the web pages is easy. All we have to do is set up links to CSS and JavaScript files from Bootstrap. There are several ways to do this. We can download Bootstrap files, add them to our repository and then set up links to those files. Another way is to set up links that point to the files available on Content Delivery Network (CDN).
In this case, we will the second way. Links to Bootstrap files can be found on the official web site: http://getbootstrap.com/ and the code that includes the Bootstrap file, which we will now set in the ‘index.html’ page, is available at the link: https://gist.github.com/cicnavi/76d62de30f31d01d228d09fdb31e8804
So let’s try some Bootstrap CSS classes. For example, we will add an effective jumbotron CSS class (example from documentation available here: http://getbootstrap.com/components/#jumbotron)
Our site now looks like this:
Of course, the entire HTML code is visible when you right click on the page, and then ‘View page source’.
Pictures and other files
In the repository we can add any files and we can organize them into directories. For example, we will add a single image to the web page. We will put images in a special directory that we will call ‘images’. The picture we’ll add is http://www.clipartbest.com/clipart-RidRKdR4T. We will do it using the GitHub.com interface.
So, the above image will be downloaded and saved to our computer. In the Internet browser, we will open a repository for our web page. First, we will create the ‘images’ directory in which we will save the images. One glimpse of creating a directory on GitHub.com is that the directory can not be empty. But we can bypass this by creating a new file and defining the name of the directory in which we will put it. For example, we will create a new file ‘index.html’ which we will save in the ‘images’ directory. The directory name and file name must be separated by a ‘/’. When you enter ‘/’, GitHub.com will recognize that the file is to be saved in the directory. It looks like this (GIF):
The ‘index.html’ file in the ‘images’ directory may remain empty because we will never run it in our case. When we enter the file name (along with the directory name), we can save the changes.
Now we will enter the ‘images’ directory and click the ‘Upload files’ button (yellow).
We will select the image we want to upload and save the changes. After we save the file, we will exit the ‘images’ directory and open the initial ‘index.html’ file. In it we can now show the picture. Part of the code that the image added now looks like this:
Notice that we simply entered the relative path to the image. The page now looks like this:
In the same way we add an image we can add any other file.
Real-Time Database
We do not have access to the local database at GitHub Pages service. But services are available on the Internet, which offer among other things, the database data storage via APIs. One such service is Google Firebase. Firebase also offers a multitude of interesting services, free of charge for personal use. This includes services for authentication, cloud file storage, web application services, advanced analytics tools, and more.
For our project, we will use the Firebase Real Time Database service. It is a database that is located in the, so called, computer cloud, that is on a server group that is accessed over the Internet. The data is stored in the JSON format as a hierarchical tree (one root element to which sub elements are added). All database data can be synchronized in real-time with all clients connected to the database.
Let’s say we want to allow any user to enter a message on our web page that will be saved in the database and that will be visible on the web page. Let’s see how we can use Firebase Realtime Database to store our messages.
We will sign in to the Firebase app (we need to create an account if we do not have it) and open the Firebase console at https://console.firebase.google.com/. Before we can start using any Firebase service, we have to define the project. So, we will select the ‘Add project’ option and enter the data. In our case, the project name will be ‘cicnavi-github-io’, modeled to the repository name of our web site.
Once we create the project, a console opens where we can select the services we want to use. We will select the ‘Database’ option.
On the database we have cards through which we can edit data in the database, rules, backups, and look at usage reports.
At the beginning, the database is completely empty (it has only a null root value). To save our message, we add a new key and save the message in its place. Let the key be called ‘helloMessage’.
By default, access to database requires authentication and user authorization. All rules regarding access rights and data validation can be specified in the ‘Rules’ tab. Default rules look like this:
For the purposes of this article, we will make an exception and allow the read and write to helloMessage key to any user. The rules for this are as follows:
Also, we will set the rule that the helloMessage key may only contain the text of the maximum length of 256 characters. The rules now read as follows:
The great thing is that our rules can be simulated. So, we will click on the ‘Simulator’ button and try to enter the data into another key (which is not ‘helloMessage’).
If we look at the details of the simulation, we can see that writing is prohibited in ‘anotherKey’ because there is no rule that allows it.
If we try to type the text into the helloMessage key, it will work. For example, we will try to simulate the entry of ‘Hello from the other side’ in the ‘helloMessage’ key.
More information on how to set up database policies can be found at the link: https://firebase.google.com/docs/database/security/quickstart
Communication with the base
At this point we have set a database, enabled access and validation of data that will be entered into the database. The next step is to enable the entry, save and display of messages on our web page. In the initial ‘index.html’ page, we will add the HTML code to enter the message, the message send button, and the place to display the entered message.
The next step is to write a JavaScript code that will save the message in our web page to the database. At the Firebase console, on the Overview page, on an individual project, we can select the ‘Add Firebase to your web app’ option (marked yellow).
You will see a code that needs to be added to the index.html file in our case.
The note states that the code should be added to the bottom of the HTML file. This code will initialize the variable ‘firebase’ using the configuration specified in the ‘config’ variable.
So, this entire code will be copied and pasted into our initial ‘index.html’ file.
After that, we have to write JavaScript code directly to communicate with the database. A documentation explaining how to write to the database and read from the database can be found at https://firebase.google.com/docs/database/web/read-and-write. First, we will define the reference to the helloMessage key previously defined in the base.
We will make variables that will link to the HTML input and display elements.
Here is the code that will show the last entered message on our web page at the first page load, and at each change of the helloMessage value in the database.
The following is a function that will save a new message to the database, which is triggered by pressing the HTML button ‘Send’.
The full HTML and JavaScript code can be viewed at: https://github.com/cicnavi/cicnavi.github.io/blob/master/index.html
Entering a message on a web page now looks like this (GIF):
Custom Domain
The GitHub Pages service allows you to use your own, custom domains that will show you to a web site located on the GitHub Pages service. Instructions on this are available at: https://help.github.com/articles/quick-start-setting-up-a-custom-domain/
Limitations
The GitHub.com service offers us to create and serve Git repositories as web sites, but only if the repositories are public. Private repository is paid.
The GitHub Pages service has the following limitations:
- The repositories that serve as web pages must be less than 1 GB
- The maximum amount of data transferred is 100 GB per month
The Firebase realtime database service has the following restrictions (for free use):
- The maximum amount of data stored in the database is 1 GB
- The maximum amount of data transferred is 10 GB per month