Skip to content

Instantly share code, notes, and snippets.

@emoravec

emoravec/Moravec_website_tutorial.md Secret

Last active January 13, 2022 17:07
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save emoravec/1462145e518a0a2758cc94ada9b987b6 to your computer and use it in GitHub Desktop.
Save emoravec/1462145e518a0a2758cc94ada9b987b6 to your computer and use it in GitHub Desktop.
Download ZIP
A quick guide on how to create a GitHub Pages website.
Raw
Moravec_website_tutorial.md

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.

Free:

  • 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

Paid:

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 gem as pip.

Steps

  1. Create a git repository on github called username.github.io where you will host your website: https://pages.github.com

  2. 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

  3. 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

  4. I’d recommend going through the motions of this tutorial to understand the structure of a Jekyll site a bit better

  5. Choose a Jekyll theme for your website

  6. 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.yml file 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.yml to indicate that you will be using the theme remotely. You will need to know the github repo for the remote_theme.
    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
    • Put theme: theme_name as the last line in your _config.yml

  7. Edit the _config.yml and other files as you please. You'll be using Markdown (see Markdown cheatsheet1 and cheatsheet2), Liquid, and pure HTML to create your webpage.

  8. 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

Use this GitHub Pages tutorial to add a custom domain. I chose hover.com to be my DNS provider and pay $15/year. I thus have the apex domain emilymoravec.com.

After you have completed these steps, you can change your url variable in your _config.yml file to be http://yourdomainname.com.

A few tips:

  1. 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.
  2. It was also recommended to me to have the host/subdomain value for these IPs, to be @ instead of *
  3. If you have an apex domain (no www) as your custom domain and would like www.yourdomainname.com to work, you can set up a CNAME on your DNS provider to have the host be www and the target name to be username.github.io
  4. 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment