Web design with Jekyll/GitHub Pages

Preface

This is a basic introduction to using GitHub Pages and Jekyll to host a web page. GitHub Pages are a feature of GitHub that allows users to host websites for individuals, projects, or organizations right from their repositories! The engine GitHub uses to accomplish this is Jekyll, a “simple, static, blog-aware, site generator”, but it also supports regular HTML content.

In this code-along we’ll cover what GitHub Pages are, why you might want to use them, and how to do so both online and locally with some jekyll basics!

Pre-requisites

Bluebird Conditions (AKA would be great to have!)

   Running Jekyll on Windows
Unfortunately Windows is not officially supported, however there are instructions for Jekyll on Windows, but it might be finicky.

Lesson Overview

The lesson will cover:

Why (and What) are GitHub Pages

Github Pages are a feature of GitHub that allows users to host static websites for individuals, projects, or organizations from a repository

Static vs. Dynamic Websites

Reasons to Use

Examples

Naming Conventions

Type of GitHub Pages site Pages default domain & host location on GitHub Publishing branch
User Pages site username.github.io master
Organization Pages site orgname.github.io master
Project Pages site owned by a user account username.github.io/projectname gh-pages
Project Pages site owned by an organization orgname.github.io/projectname gh-pages

Online Editing: Automatic Page Generator

  1. Create a new repository (github.com/new)
    • There are 4 types of GitHub Pages site (in the table above and on GitHub)
    • following naming conventions is really important! .github.io for user and organizations
  2. Navigate to Settings and click Automatic Page Generator
    Or just go to generated_pages url for your repository:
    https://github.com/<username>/<repository>/generated_pages/new
    • Make some edits to the content
    • Select a theme/layout
    • Publish!
  3. We have a website!
    <username/orgname>.github.io/<projectname>/
    • Let’s check it out
  4. Make an update
  5. Check out the commit history

Working Locally: Git and Jekyll

  1. First, we need to make sure we have everything installed

     $ git --version
 git version X.X.X
 $ jekyll -v
 jekyll X.X.X

  2. We’ll have to create (or choose) a repo for a project

     $ git init first-website
 Initialized empty Git repository in <path/to/current/directory>/first-website/.git/

Note: There are a few extra steps if you want a project page for an existing repository! Please see: help.github.com/articles/creating-project-pages-manually

Jekyll Basics

Jekyll is a package (ruby gem) that makes a jekyll executable available from your command line.

There aren’t too many commands you need to get going: jekyll new and jekyll serve
and another one: jekyll build but serve calls build, so the command is not often needed

let’s test them out:

$ jekyll new first-website
New jekyll site installed in <path/to/current/directory>/first-website.

So we have a project, let’s check out what’s there!

$ cd first-website
$ ls -lFA
$ git status

Lots of files. Before we dig in let’s try to get our website built

$ jekyll serve
... <lots of details including file paths>
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.

…and check it out in the browser.

Why don’t we try to make some changes and see how it looks? Let’s edit index.html, see how it updates in the browser automatically

If we want to make more substantial edits to the site name, our contact details we’ll have to modify _config.yml, but it won’t update in the browser until we re-serve the page

Anatomy of a Jekyll Project

Before doing more let’s take a look at all those files and folders in our directory again. Jekyll docs and the tree command can do a better job than me…

$ ls -lFA
$ tree

A clumsy equation for jekyll:
_* files and folders * *.html/markdown/md/textile = your static site (in _site)

Front matter & Liquid Tags

In order for those *.html/markdown/md/textile files to be transformed into working static pages, jekyll makes use of:

YAML Front Matter (Yet Another Markup Language YAML Ain’t Markup Language), once again I’ll lean on jekyll docs

$ cat about.md
---
layout: page
title: About
permalink: /about/
---
...

and Liquid Filters and Tags (A templating Language for handling dynamic content), thrice those handy jekyll docs

$ cat about.md
---
...
{% include icon-github.html username="jglovier" %}
...

I hope that is enough to start, there are lots more fiddly bits, but the docs and additional resources (below), as well as google, have lots to offer!

Making your site live

<movie training montage>

Okay, we’ve got a great site, spent some time on the content and now we want everyone on the internet to see it too.

Before we get this up on GitHub we should make sure that the repo is set up to not commit the static version of the site. GitHub does not need it to host your site, as they use jekyll to generate sites on their end too:

$ git status
...
.gitignore
...
$ <cat/touch> .gitignore

Github helpfully publishes all sorts of template .gitignores, the jekyll one only has three items…

While on GitHub let’s set up our repo, remember the naming conventions above: <username/orgname>.github.io/<projectname>/

now, to commit our changes…

$ git checkout -b gh-pages
$ git add .
$ git commit -m '<some meaningful commit message>'

and push them to GitHub…

$ git remote add origin <repo address>
$ git push --set-upstream origin gh-pages

success! (hopefully…?)

Using Themes

Many times you won’t want to build up your site from scratch, instead you’ll continue the lofty tradition of standing on the shoulders of giants and use a pre-made theme:

jekyllthemes.org

If you are feeling overwhelmed so many I selected a couple:

And more…

Resources

Glossary