Hosting a website with GitHub Pages

My website seaheuchin.info is a labor of love for me – it is a work of family history and biography that I researched and started to write up in 2007, but only some months ago did I publish it online as a website.

screen-shot-2016-12-04-at-11-23-23

Web-publishing is the poor(er) man’s self-publishing, but it does offer some advantages over paper. I can easily update the site with new features, such as photographs and transcriptions of original documents, and also incorporate interactive features like maps and timelines. It’s perfect for a serial procrastinator like me, because I can make something that is mostly done but not yet perfect available as a working version. For example, I’m still working on text boxes to explain the historical background for something mentioned in the main text of the biography – many of them are already up, but for some I have only an outline of what I would like to write.

In this blog post I’ll explain what free tools (“free” in the sense of not paying money for it, not the “free” in Free Software Foundation) I’ve used to build and host the website. I want to show how a hobbyist with modest web skills, like me, can still get things online quickly and painlessly.

Part 1 – Planning your needs

What I wanted:

  • Platform where it is easy to upload and manage pages
  • Full control over content and formatting
  • Spend as little money as possible
  • Data backup and archiving; portability of content, in case the hosting service goes out of business some day

What I didn’t need:

  • “Fancy” interactive content (i.e. only using static pages, Javascript)
  • High bandwidth (I don’t anticipate more than a few visitors a day, at max)
  • Search engine optimization

Part 2 – Putting the pages together

I marked up the webpages myself in HTML and CSS. The original was just a word processor document, so I simply copied the contents into a plain textfile and added the HTML markup around it. This was straightforward, though on hindsight I would have tried to find a way to automate marking up all the footnotes. HTML and CSS are quite easy to pick up. I had taught myself how to build simple webpages when I was in school (old-timers will remember Geocities, Lycos, webrings, and all the other good stuff), but I needed a bit of refresher, so I hopped over to w3schools to check out their tutorials.

A few notes:

  • I kept the design quite basic, because that’s about as much CSS and HTML as I know.
  • CSS is really useful because
    • It enforces the discipline of marking up the HTML properly, which…
    • Encourages careful planning of the relationship between content and appearance, and…
    • It is easier to edit one CSS file than a hundred HTML files.
  • The color scheme has no special significance, but I hope that it is at least easy on the eyes.
  • The writing-mode CSS property for text orientation (I used it for rendering vertical Chinese text) is not supported in all browsers – caveat emptor!

Part 3 – Bells and whistles

To visualize data, I used Google Charts, which uses Javascript. I wanted to be able to embed small maps, timelines, and so on in my pages. I’d previously used Charts for another project so I was already aware of it.

The data that I want to display, e.g. this timeline, is embedded in the header of the HTML file, so you have a local copy of your data and don’t have to manually upload anything. However, the actual script that renders the charts are on the Google servers, and so using Charts requires that you accept their terms of service, and to be connected to the Internet. There are open source libraries for data visualization that are even more extensible and feature-rich, such as d3, but I wanted something straightforward, and for this project, data privacy was not a concern.

I also added a favicon – that little icon that you see in the address bar or the browser tab when you load some websites. Different browsers have slightly different standards for recognizing favicons, as documented in the Wikipedia article. I used the standard method of putting a link in the HTML page header, which is explained here. At first I wasn’t sure if it would work properly with my domain redirection settings, but it did!

screen-shot-2016-12-04-at-11-18-50

This is a favicon!

Part 4 – Hosting the website

At first I had the files hosted on Dropbox, which has a Public folder feature. By sharing the URL of the index.html file, I could share my draft version of the website with friends to get their comments. To get the custom domain seaheuchin.info, I signed up with GoDaddy.com, but there are many other domain name merchants out there to choose from.

Why .info? It just happened that .info names were cheaper (certainly much cheaper than .sg) and seemed more appropriate than others like .com or .net. To redirect the custom domain to the pages hosted on Dropbox, I simply pasted the Dropbox URL into the “site redirection” option in the GoDaddy admin page.

screen-shot-2016-12-04-at-11-21-29

It was so easy before…

Unfortunately Dropbox has stopped offering this freebie, and I had to find another hosting option. I also wanted a way of keeping track of the changes that I make to the pages, in case I wanted to undo certain edits. For these reasons it was natural to migrate the files to a Git repository, and post it on GitHub.

Git is a version control and collaboration system originally developed for software projects like Linux. In combination with the online platform GitHub, which is essentially a service for archiving and syncing repositories over the Internet, it is very popular among software developers and scientists who want to share the code that they use to analyze data. However it’s not just for software – there is a great article on how some people are using GitHub to collaboratively edit a collection of taco recipes. If I ever find someone who wants to collaborate with me on my website, e.g. by doing multimedia features or translations, we could easily sync our work through Git.

screen-shot-2016-12-04-at-11-15-32

One way to use Git

For websites, GitHub offers what is essentially free hosting through their GitHub Pages feature. The original intention was to make it easy for programmers to create websites associated with their software projects (e.g. to hold documentation, manuals, FAQs), but people now use it to make homepages for themselves, and also stand-alone websites like mine. Once you have gotten accustomed to GitHub it is quite straightforward to set up a website with GitHub Pages, by following the instructions on their website. It was a good option for my project because it is just a set of static HTML pages with no PHP or other dynamic content. Also the change history of the repository is publicly visible and time stamped, and the contents are backed up on the GitHub server, so if my computers and backups somehow get mashed up there is still another copy sitting around.

screen-shot-2016-12-04-at-11-17-37

Another way to use Git – with the GitHub desktop client

There are several guides and blog posts online about setting up a webpage with GitHub pages, so I won’t rehash the details here.

How to set up a custom domain to point to a GitHub project page: When the pages were still hosted on Dropbox I set up the redirection option with URL masking. However I wasn’t satisfied with this because a visitor would not be able to directly link or bookmark one of the pages in the site. So I decided to set up redirection “properly”. This was initially a bit confusing for me because most of the instructions online were for redirecting to a GitHub user page, rather than a project page, but after a while I found a helpful answer on StackExchange. Here’s what I did:

  • Create a plain text file in the repository with the name CNAME, and in the file type a single line with the name of the custom domain (seaheuchin.info). Git add, commit, and push to remote.
  • Log into GoDaddy account and open up the DNS admin page for my domain
  • Create a new record of type “A”, and point “@” to the IP address 192.30.252.153. Create another record for IP address 192.30.252.154. These addresses were correct as of Nov 2016, but they may have changed in the meantime, so check out the GitHub documentation.
  • Create a new record of type “CNAME” and point “www” to kbseah.github.io. The project name does not have to be specified, because the GitHub server will use the CNAME file created earlier in the repository to figure that out, i.e. you can have multiple repositories in your account each linked to a different custom domain.

Part 5 – What’s next?

One day I’d like to write up a script to convert the HTML to LaTeX so that I can have a PDF version for download, for people who would like to view it offline, or who prefer to print it out as a physical book to read.

In the meanwhile, I have a pretty decent-looking website (imho) which serves its purpose, and which I can tinker with when I’m bored. The skills that I’ve picked up along the way will definitely be useful for future projects!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s