This demo was created for use in trainings to have educators play with GitHub, GitHub Pages, and Jekyll. This guide is meant to help Git and GitHub beginners get up and running with GitHub Pages and Jekyll.

It assumes you know very little about Git and GitHub. We’ll be using a little bit of Markdown, and you may work a bit with HTML and CSS. You do not need to be an expert in any of these languages. The idea is that you’ll play and learn by doing.

Some things to know

Git, GitHub, and GitHub Pages are all closely related. You can think of Git as the pipes to get things done and keep track of projects. GitHub and GitHub Pages as places to publicly store the work you finish working with Git.

Git is a version control system that tracks changes to files in a project over time. Git will allow you to record what changes were made to a file and who made them.

When we work with Git, we’ll have opportunities to think about versioning. Version control is the management of changes to documents, computer programs, large websites, and other collections of information.

GitHub is a web hosting service for the source code of software, web development, or other text-based projects that use Git. If this is your first time using GitHub, you’ll need to create an account.

GitHub Pages are public web pages hosted for free through GitHub. GitHub users can create and host both personal websites (one allowed per user) and websites related to specific GitHub projects.

Imagine you work on a letter using Microsoft Word on your computer. You upload the letter and convert it to a Google Doc to allow you to share it out with others for feedback. Later on, you decide to share this Google Doc using Google Sites, or simply publish the Google Doc to the web. In a general way, Git would be the Word doc and content you create on your computer. GitHub would be like using Google Docs to share the content of your letter. GitHub Pages would be like using Google Sites to publish content to the web.

Jekyll is a static site generator. It is a throwback to the days of static HTML before databases were used to store content of your websites content. For simple sites without complex architectures, like a personal website, this is a great option. When used with GitHub, Jekyll will automatically re-generate and publically make website pages available for all.

Let’s Build a One-Pager

In some of my workshops, I’ll have participants play with a simple document to get their feet wet as they play with the tools. This one pager template is an idea I borrowed from Doug Belshaw to get people working.

For this demo, you’ll be working with this GitHub repo (repository) that I created to serve as a template. You can check out the live version here.

Step One. Log in to GitHub. If you don’t have a GitHub profile, you can create one here. Once you’re logged in, open this link in your browser: https://github.com/wiobyrne/onepager.

Step Two. Click on the little “Fork” button at the top right corner. Wait until the repo is forked.

Step Three. Now you have your own copy of the template to use and remix. Go to repository Settings and scroll down to the “GitHub Pages” section. Select “master branch” under the “Source.” Read more here.

Whenever you commit to this repository in GitHub, GitHub Pages will run Jekyll to rebuild the pages in your site, from the content in your Markdown files. You can use the editor on GitHub to maintain and preview the content for your website in Markdown files.

Markdown is a lightweight and easy-to-use syntax for styling your writing. Keep this page open to help you as you write, edit, and revise.

This post is a great resource to understand the what you’re doing.

Some other options

Jekyll Resume Builder (GitHub repo / live version) – This repo from Tim Klapdoor started out with the idea of working out how to build a resume with Jekyll. Rather than Pages and Posts it makes use of Collections to populate the single page.

Classroom Resources Manager (GitHub repo / live version) – This repo from Jorge Sanz serves as a template for teachers that want to generate a website to provide resources by course to their students.

Personal Website (GitHub repo / live version) – This repo from Jonathan McGlone is a great example of an opportunity to create a personal website and blog using Jekyll and hosting it for free using GitHub Pages. Step-by-step guide here.

AcademicPages (GitHub repo / live version) – A Github Pages template for academic websites then extended to support the kinds of content that academics have: publications, talks, teaching, a portfolio, blog posts, and a dynamically-generated CV.

Photo by Roman Synkevych on Unsplash