Hosting static websites with GitHub Pages
GitHub Pages allows you to host a website
directly from your GitHub repository. Your site will then be hosted
under your own GitHub subdomain. For example,
OpenTechSchool has the repository
which is automatically published to
GitHub automatically handles the publishing and serving of the site.
All we have to do is push to our repository on the
and GitHub will take care of the rest.
There are a few different ways to get started with GitHub Pages, we’ll be looking at using the GitHub Pages wizard and rolling your own with Jekyll.
The Automatic Page Generator
GitHub provide an automated system to bootstrap an empty repository for GitHub Pages. It allows you to pick from some premade templates so you won’t even need to clone your repository to your local machine.
Create a blank repository. Any name will do. We’ll use
github-for-cats as an example.
Then go to the Settings tab (in the list of buttons on the right, the old name was “Admin” - these screenshots are slightly out of date.)
The generator will build just the front page for you, but you can get a lot done here.
Then the styles are all fancy and modern and new.
Now you can look at your site online!
Oh snap! Actually, you’ll might need to wait a while for the first time. But it’s worth it! After the first time it gets much quicker at publishing.
And you’re done!
You can actually make a GitHub Pages site yourself with just a blank repository. It’s just a little more work because you’ll need to get all your HTML/CSS/JS yourself and commit it to your repo.
The key thing to remember is that your site must be on the
gh-pages branch. If you commit to the
master branch, which is the
default branch in git, then GitHub will not care. It only looks to see
if you have a
gh-pages branch (if it watched
master it would try
to publish almost every GitHub repo).
Start by creating a repository on GitHub and cloning it locally. Be sure
to use your own URL to execute the
clone command on.
$ git clone firstname.lastname@example.org:stevenfarlie/blank.git Cloning into 'blank'... warning: You appear to have cloned an empty repository.
Git is correct: we have cloned a blank repository. It doesn’t even
have a branch or an initial commit. Let’s start by creating a
gh-pages branch for the initial files:
$ git checkout -b gh-pages $ git status # On branch gh-pages # # Initial commit # nothing to commit (create/copy files and use "git add" to track)
You can download a zip file with minimal website
the files into your repository, then
$ git add index.html site.css site.js $ git commit -m "Basic GitHub Pages site" [gh-pages (root-commit) 60ce662] Basic GitHub Pages site 3 files changed, 46 insertions(+) create mode 100644 index.html create mode 100644 site.css create mode 100644 site.js
Now we can
push to GitHub, but remember that we are pushing to
gh-pages, which doesn’t exist yet on our GitHub repository
$ git push origin gh-pages Counting objects: 5, done. Delta compression using up to 2 threads. Compressing objects: 100% (5/5), done. Writing objects: 100% (5/5), 989 bytes, done. Total 5 (delta 0), reused 0 (delta 0) To email@example.com:stevenfarlie/whatever.git * [new branch] gh-pages -> gh-pages
And bask in the glorious result! You’ll find your site published at:
Jekyll - A little more dynamic
Things get even fancier with Jekyll. GitHub has native Jekyll support. It let’s you write pages in Markdown with simple templating and support for blog posts. It’s what we use at OpenTechSchool for our blog.
You’ll need a Ruby setup to get the most out of it, and at least the
jekyll gem installed. Maciakl has provided a simple Jekyll template
here which you can
use to get started. But be careful to switch to the
because their repository is using