A general guide to create a webpage using Github Pages.
I looked into various options for creating a professional presence on the web. There are two options: free and paid.
- GitHub Pages, hosting and site creating through Jekyll
- Google Sites, hosting and site management
- Wordpress templates, but you have to host it somewhere
- Wix, hosting and templates
- Squarespace, templates and hosting
In the end I chose to use GitHub Pages because I already use git, it was free, and it gave me somewhere independent to host it. I recommend that you use GitHub Pages if you already use git and are up to learn some new things about website building. And if you find a Jekyll theme that you like. If you haven't used Ruby or jekyll before, there is a learning curve, but it isn't too bad.
In the summer of 2020, I created my website using a combination of Github Pages, a Jekyll theme, copying necessary template code from the theme repository, and editing the template on a Mac using Sublime. Listed below are the versions that I used:
- Mac: High Sierra 10.13.6
- Ruby 2.7.1p83
- Jekyll 4.0.1
- Jekyll theme: Type-on-strap
Github Pages is where your site is hosted. Jekyll is the software that is used to generate your site. And Liquid, Markdown, and HTML are the languages/syntax that Jekyll reads to create your site. Ruby is the language that Jekyll is written in. Think of Ruby as Python and a Ruby
Create a git repository on github called username.github.io where you will host your website: https://pages.github.com
Clone that repository on your local machine and if you will be using a Jekyll theme get rid of everything that is in the repository
Install ruby then jekyll (see https://jekyllrb.com/docs/)
a. Install Ruby: https://jekyllrb.com/docs/installation/
b. Within the git repository, install Jekyll and bundler gems:
$ gem install jekyll bundler
I’d recommend going through the motions of this tutorial to understand the structure of a Jekyll site a bit better
Choose a Jekyll theme for your website
There are two cases, a) you plan to mostly follow the theme and not change how it looks and functions, or a) you plan on changing the theme quite a bit.
a. If you plan on mostly using the theme,
- In your local git repository following the steps beginning at "To create a new Gemfile..." in the step-by-step guide.
- Download the
_config.ymlfile and begin to edit. Create assest/pages directories and copy style files to overwrite styles according to your needs.
- Put the following two lines as the last lines in your
_config.ymlto indicate that you will be using the theme remotely. You will need to know the github repo for the
theme: theme_name remote_theme: github_account/theme_name
b. If you plan on changing quite a few things about the site,
- Clone your chosen Jekyll theme repository
$ bundle install
theme: theme_nameas the last line in your
To see edits to site:
$ bundle exec jekyll serve
Click on the link this command generates in the terminal to see your edits. On a Mac you can ctrl+click on link -> open URL.
Linking a custom domain name
After you have completed these steps, you can change your
url variable in your
_config.yml file to be
A few tips:
- On my DNS provider I added A records for each of the first 3 IP addresses for GitHub Pages. I was told that having at least two is best practice, though your site will still function with just one.
- It was also recommended to me to have the host/subdomain value for these IPs, to be @ instead of *
- If you have an apex domain (no www) as your custom domain and would like
www.yourdomainname.comto work, you can set up a CNAME on your DNS provider to have the host be
wwwand the target name to be username.github.io
- Know that it can take up to 72 hours for DNS changes to take full effect, and up to an hour for an HTTPS certificate to be requested
Placing a template on GitHub Pages
-Create the project repo, add the “index.html” file and commit. Alternatively, initialise the repo with a README.md file, and change that file to the index.html (see this guide).
- If your website doesn’t appear soon afterwards, it may just be taking a long time to create the first time, or you may need to go to “https://username.github.io/index.html” in your browser once, and then the page should load after that (see answer by Chetabahana here:). Note that a confirmation e-mail that the website was published was never received.