GitHub Pages

Hosting static websites with GitHub pages

Learning objectives

This tutorial will walk you through the steps of creating a personal website hosted on GitHub at a URL specified by your username: http://{github_username}.github.io. By the end of this tutorial you will know how to create this website, and others, from your GitHub account. This tutorial will probably take 15-45 minutes to complete.

GitHub pages

In addition to its many other uses, GitHub serves a similar role as LinkedIn for the tech industry, as a public social network for sharing code and demonstrating your coding experience, and this extends similarly to fields in biology like bioinformatics and biotech. In fact, your GitHub profile can be an important resource when applying for jobs to show concrete examples of your work.

GitHub has embraced this status by providing tools and services that make it easier to share the contents of your GitHub repos not only using the standard GitHub interface, but also by serving those contents through customized webpages hosted by GitHub. This framework is generally referred to as GitHub pages.

Static websites

More generally, github-pages is an example of a broader category of websites called static websites. This generally means that these sites are very simple, composed of only HTML, CSS, and JavaScript, with no back-end database and server framework (e.g., PHP or Python). Thus, these sites do not offer as much user interaction options as more complicated websites; but, as a trade-off, they are much easier to develop, and also faster and more secure.

For these reasons static websites have become very popular as a form of personal or lab website in Academia. There is a large community of developers who have created open-source web design themes and frameworks for easily styling static websites by cloning existing GitHub repos and simply substituting your details in place of the existing ones. Thus, you can create beautiful websites without having to know any HTML or CSS at all. This sounds a bit like squarespace, right? Well, it pretty much is, except free.

GitHub has taken this approach one step further to make it even easier to create static webpages. Any GitHub repo can be made into a static website simple by flipping a switch on GitHub. In its most basic form the Markdown content in the README file will serve as content for the website and a default CSS theme will be applied, unless you add further styling yourself.

Examples

As an example, my lab website (https://eaton-lab.org) was created as a github-pages site using a popular template available online that I cloned from a GitHub repo. Similarly, our course website (https://eaton-lab.org/hack-the-planet) is an example of a static site I created using a mkdocs-material design framework. Both websites are simply a collection of files and folders hosted in a repo on GitHub. (I went an extra step to pay for the domain name eaton-lab.org, but otherwise the basename of the site would be eaton-lab.github.io.) You can view the GitHub repos associated with these two websites at the following links:

• https://github.com/eaton-lab/eaton-lab.github.io
• https://github.com/eaton-lab/hack-the-planet

Steps to creating a Github pages site

1. Go to Github.com, select Repositories and then click New from the upper right corner. Name the repository {username}.github.io, replacing {username} with your GitHub username (and no curly brackets). Make the repository public and add a README file.

2. On the repositories webpage click on the Settings tab in the upper right corner (if your browser window is not expanded it may appear under a collapsable button appearing as "..."). You can set many options for specific repositories under its Settings. Scroll down until you find the section labeled Pages.

3. Click on the button under Source and select your main branch. It will then list an option for a folder name, set it to the default option (root).

4. Select a Theme if you wish, or leave it as the default. This will create a commit to your repository adding a file called _config.yml which tells GitHub the theme to apply.

5. That's it. It may take 5-10 minutes for your website to first appear. Try visiting http://{username}.github.io (with your username) until you see it appear. Better yet, choose the Actions tab and you can watch your new site build and deploy and then you'll know when it's ready when the green check mark appears.

Editing your static website

By default this site will serve the contents of your README.md file as the source of your website. In other words, you can fill the content of your website by writing in Markdown. Even though the Markdown language is very simple, you can actually create pretty nice looking websites using just this simple method, along with the pre-built themes. If you are familiar with HTML, or want to learn it, you can actually combine HTML and Markdown into the same document. HTML and CSS will allow you to add a lot more styling.

To see an example visit the website of our example student Phylo here: http://hackers-test.github.io and check out their GitHub repo for an example of what the raw files look like: https://github.com/hackers-test/hackers-test.github.io. You can see in this example that all of the content of site is just a few lines in the README file.

How/why this works

GitHub builds these sites using a web framework called Jekyll. If you get very interested in this topic then I recommend reading through the jekyll documentation and learning more about how to develop these sites from scratch. In our example above, GitHub is doing most of the hard work for us. But you can actually use GitHub in either way, having it run jekyll behind the scenes, or by running jekyll yourself and uploading the contents to the repo. To see an example of the later see the repo for our course website in the docs/ folder at https://github.com/eaton-lab/hack-the-planet.

The basename {username}.github.io will be reserved for you only for this specific reposotory that has this name. But, you can create webpages for other repositories by visiting their settings and enabling github-pages. For example, if you did this for your hack-2-shell repo then it would become available at the address https://{username}.github.io/hack-2-shell.

Academic websites

In some ways, this tutorial is just a fun exercise for learning about git and GitHub, but on a more serious note, developing a professional academic website is an essential resource as part of your career development as a graduate student. It is a simple way to put your name, interests, papers, talks, etc. online, so that you have a google-searchable presence as a scientist. This website doesn't necessarily need to be the one you use, but it provides a simple way to make a site that not only serves this purpose, but for those who are in the know, also signals to them that you are tech-savvy enough to have created it.

Assessment

Your assessment for this tutorial is intended to combine three elements that you have learned: (1) using Markdown; (2) using git; and (3) hosting sites on Github. You are meant to complete the following tasks using command line tools in your terminal.

Alert

Action: Edit the content of your personal website on GitHub to represent yourself (or your Github profile persona if you are uncomfortable with sharing personal info). Make it professional, with a photo (of you or some topic) and a description of your research or academic interests. Spend some time on it, but it doesn't need to be exhaustive for now, you can return and add more content to it at any time later.

Your grade for this assignment will be based on the following:

Part I:

• Edit the settings of a repo called {username}.github.io to make it into a Github-pages website (you likely already did this above).
• Clone the repo to your local computer at ~/hacks/{username}.github.io
• cd into the repo.
• Edit the README content using Markdown (and or HTML) to include at least some text and an image. Revisit the Markdown resources if you need help with this, and look at code in the examples linked above.
• add, commit, and push to origin main to view the changes at {username}.github.io.

Part II:

• using mkdir create a new directory called data/ in the repo.
• use wget to download a CSV file from https://eaton-lab.org/data/iris-data-dirty.csv to your repo.
• move this file into the data/ folder if not there already.
• use git add to stage the folder and file data/iris-data-dirty.csv for commit.
• use git commit to commit these changes.
• use git push to push these changes to your origin main.
• wait a few minutes and then visit {username}.github.io/data/iris-data-dirty.csv. You should be able to see or download the CSV file (depending on your browser).

Congratulations, you've created a personal website, and now you've also created a subfolder within it where you can store data files that will be easily accessible from this web address. If the last step worked then you were successful. If not, there must have been an error somewhere. Keep trying. If you get stuck, visit the course chatroom.