Everybody knows that maintaining code with github is one of easiest and most popular ways to work and collaborate on software projects. What’s less well known is that it can also host those projects too. Back in 2008, Github launched Github Pages as a quick and dirty place to build documentation sites and demos for projects, and it has since matured into one of the easiest and most cost-effective ways to host static content on the web.

Why use github pages?

In short - it’s quick, it’s easy and it’s cheap. All you need to do is create a repository, commit your static files and tell github which branch is your website. It’s that simple. But wait! there’s more! You can also configure custom domains - pointing your own domain at github via DNS allows you to host your entire website on github, if you so choose. On top of that, it even integrates with Jekyll to easily manage your content.

Wait, what the heck is Jekyll?

Jekyll is a lightweight ruby framework for building and maintaining static websites. It comes with a robust and flexible templating engine to build your site structure and layout, it’s fully theme-able via html and css, and it uses markdown to manage your site’s content. When you’re done building your site, it spits everything out as static html files that Github Pages uses for your website.

This all sounds great, but what’s the catch?

As great as this all sounds, there are a few limitations. First and foremost, is that you’re limited to static content only. If you’re looking for dynamic content and lots of interactivity, you’ll need to be a bit creative with how you implement it. Whilst there’s no server to render content for you, there’s nothing to stop you pulling in extra functionality via an external API with javascript.

Github also limits you to one site per account/organization. You also need to have a github premium account (at $4 a month) if you want to use it with private repositories or custom domains. So if you’re looking to host multiple sites, you might better off looking elsewhere.

So if you’ve made it this far and you’re still keen to host your site on github, then look no further, I’ll show you how!

Prerequisites

Going into this tutorial, I’ll expect the following

  • Experience with html/css
  • A working knowledge of git, and a github account
  • At least a basic understanding of Ruby, and a system with Ruby 2.4.0, RubyGems, Make and GCC
  • Know a bit about markdown.

My Environment

My environment when writing this tutorial was Ubuntu 20.4 under WSL 2, but your mileage may very depending on your setup. I know Mac users will want to look at Brew, and I strongly recommend Windows users set up Windows Subsystem for Linux. It’s easy to do and seems to work pretty much flawlessly with any Linux distro I throw at it. If you really don’t want to do that, than you might want to try Choco, so good luck with that.

Step 1 - Installing Jekyll

The first thing we need to do is get Jekyll up and running on your local machine. To do this, you’ll also need to have Ruby, Make and GCC installed for it to function properly. Real Ruby developers will probably want to use RVM, but if you don’t know what that is already you probably don’t need it. Instead here’s the quick and dirty approach:

  1. Install ruby: sudo apt-get install ruby ruby-dev
  2. To ensure your ruby is new enough, ruby -v should be higher than 2.4.0 (mine is 2.7.0)
  3. Install all of the compilers: sudo apt-get install gcc g++ make
  4. Make sure RubyGems is installed correctly: gem -v should return something like 3.1.2
  5. Install jekyll: sudo gem install jekyll (NB. installing gems with jekyll can pose a bit of a security risk, but if you’re only ever going to use ruby for jekyll then you should be just fine)
  6. Check that jekyll is installed by running jekyll -v. You may need to restart the terminal

Step 2 - Making your first Jekyll site

Okay, so you’ve got Ruby and Jekyll installed, and now you’re ready to build your first website.

  1. Make a folder for your websites and navigate to it in the terminal. I put all mine in my user directory, but you do you.

     mkdir ~/my-websites
 cd ~/my-websites

  2. now you’re ready to make your first jekyll site:

    jekyll new my-new-website
cd my-new-website

  3. If all goes to plan you should find yourself in a directory with the following file structure

     ├── 404.html
 ├── Gemfile
 ├── Gemfile.lock
 ├── _config.yml
 ├── _posts
 │   └── 2021-04-03-welcome-to-jekyll.markdown
 ├── about.markdown
 └── index.markdown
    index.markdown This is your homepage
    about.markdown This is an example about page
    _posts This will contain all blog posts you write for your website
    _config.yml This file contains a range of settings for configuring your site
    404.html This is the error page that will be displayed if a user tries to navigate to a page that doesn’t exist
    Gemfile & Gemfile.lock These tell your system which prerequisite to install for Jekyll to run. You don’t need to worry about these for now
  4. We need to change some settings in _config.yml before we’re done, so open it in your editor and paste in the following: 
     title: Your Site Title
 email: your@email.com # optional
 description: >- # this means to ignore newlines until "baseurl:"
   A short description of your website here
 baseurl: "" # the subpath of your site, e.g. /blog
 url: "" # the base hostname & protocol for your site, e.g. http://example.com
 twitter_username: yourtwitterhandle # optional
 github_username:  your-github-handle # optional

 # Build settings
 theme: minima
 plugins:
   - jekyll-feed
  5. To see your site in action, just run jekyll serve and visit http://127.0.0.1:4000 in your browser.

Host on github

Congratulations! You’ve just made your first Jekyll page. Now all you need to do is put it on github. To do this, you first need to make a special github repository:

  1. Login to your github account, click the ‘+’ at the top right of the website, and then click ‘New Repository’
  2. To make a github pages site, the repository name has to be your-github-username.github.io
  3. Add a description if you fancy, choose ‘public’ or ‘private’ (you need premium for a private site), and leave the three tick-boxes for ‘README’, ‘.gitignore’ and ‘license’ unticked. When you’re done, click ‘create repository’.
  4. Copy the repository location from the green ‘code’ button

  5. Now go back to your terminal, and from your site’s directory run the following:

    git init
git add .
git commit -m "initial commit"
git remote add origin git@github.com/your-repository-path
git push -u origin master
  6. If you refresh the page of your repo, you should now see the contents of your directory has been listed. Now we just need to tweak a few final settings and you’re good to go
  7. Click on the ‘settings’ tab underneath the repo title, and under ‘Options’, scroll down until you see the ‘Github Pages’ section.
  8. In the dropdown, pick the branch you want to use as a source for the site content. If you’ve been following along so far, this will either be master or main
  9. It will also ask you to pick a directory within the branch where there content resides. For jekyll sites, just leave this as /
  10. When you click save, you’re done! if you visit https://your-username.github.io you should see your shiny new website. (nb: it can take a minute or two from pushing to the repository to the site content updating, so if you don’t see anything straight away, there’s no need to panic)

Setting up a custom domain

So you’ve just made your first Jekyll website and successfully put it on the internet with github pages. That leaves us with one last step, to configure your custom domain. You have a choice here. you can set up an Apex Domain if you want to point your entire website to Github pages (eg. http://example.com), or if you prefer you can also just use a subdomain if you wish to use your apex domain for something else (eg. http://blog.example.com).

For both approaches, you’ll need access to your registrar’s account, or wherever you normally configure your DNS settings.

Apex domains

To set up an apex domain, we first need to tell github which domain to listen for. To do this, you need to create a file in the root of your project called CNAME. In this file, simply add your domain name. So if you wanted to use www.example.com, the entire file should look like this:

example.com

After you’ve done this, we now need to configure your DNS. Github has four IP addresses open for github pages, and you need to create four A records for @; one for each IP. These IP addresses are:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

You also need to create a CNAME record for www, and point this to your-username.github.io. This will automatically redirect www.example.com requests to example.com.

Subdomains

If you only want a subdomain, things are a tiny bit simpler. As with an apex domain, you need to create a CNAME file in the root directory of your project, but this time we need to include the subdomain you want to use also:

blog.example.com

To configure your DNS settings, you only need to create a single CNAME record and point it to your-username.github.io

Conclusions

So that’s all there is to hosting websites on Github pages. Don’t forget to watch this space, in the future I’ll be covering Jekyll in some more detail, including how to configure posts and pages, how to include third party services - such as comments and analytics, and also how to build your own page templates and customize your theme.

If you like what you’ve read, or spotted any glaring errors and omissions, then feel free to leave a comment below (assuming I’ve built commenting yet!).