magic flying camel
This repository contains a starter "seed" for creating a Jekyll-based Github Pages page.
If your repository is located at
github.com/<user>/<repo-name>, the Github Pages page will be available at
Jekyll is a ruby-based package for creating a static site - a site composed of HTML/JS/CSS files, which is basically anything that doesn't require the server to do a lot of computation. Github hosts these files so they're served quickly and reliably.
This is a walkthrough of how to get a simple Jekyll Github Pages page all set up.
How it works
Let's cover how this all works first, before we cover the steps.
You'll start by copying the
docs/ folder from this repository
docs/ folder of your repository.
This folder contains the "source" of your static website - the plain markdown files and HTML templates that are used to assemble the final page's static content.
Github Pages does the actual work of assembling the static content. It offers this service for free, if you agree to use Jekyll... (and get drawn into the Ruby black hole...)
docs/ folder contains some Ruby files that you can use
to configure the site.
Quick start: no ruby
If you want to avoid using Ruby...
Clone magic-flying-camel somewhere on your hard drive
$ cd /tmp $ git clone https://github.com/charlesreid1/magic-flying-camel $ cd magic-flying-camel
docs/ folder to your own repository:
$ cp -r docs /path/to/my/repo/docs
Although this template is designed for minimal configuration, there are a few Jekyll settings you will have to set. These include the site title, github URL, and author info.
These are located in a YAML file:
You can add Markdown files to the
docs/ folder and they will
be rendered in the final site. Use magic-flying-camel as an example
of how to create a multi-site static site where things inter-link.
Don't forget the Last Step (below).
Hosting locally: with ruby
If you want to brave the confusions of Ruby...
- On a Mac: Homebrew is recommended. It runs on Ruby.
- On a Linux: aptitude?
- On a something else: good luck, you probably know what you're doing.
This is where things get confusing.
gem, which is a ruby thing, but different from Ruby,
because it is used to install things:
$ brew install gem # or $ apt-get install gem
bundle, which is used to install things, but different from gem:
$ gem install bundle
Now you need to update your
$ bundle update
jekyll build to build the site in
bundle to install things):
$ jekyll build
To view the site locally:
$ jekyll serve
available now on port 4000!
Don't forget the Last Step.
The Last Step
The last thing you'll need to do is change the settings of your
repository to turn on Github Pages. From the repository page,
click Settings, and scroll down to the section called "Github
Pages". From the drop-down menu, select "Use the /docs folder
for Github Pages." This will automatically look for a Jekyll
site in a directory called
docs/ in your repo and will
render it into a final static page (Github takes care of the
Ruby stuff). When you update its contents in a commit or various
commits, and you push commits to Github (in plain English:
if you run
git push origin gh-pages
after making commits to the
gh-pages branch), Github will
automatically use Jekyll (which is a Ruby package) to create
static content, and the updated contents will be available at