Dr. Jekyll and Mr. GitHub Pages

Time ago I started using the GitHub Pages service just for fun:

• http://davidemoro.github.io/tour_knight_angularjs (just my first demo app based on AngularJS)

With GitHub Pages you can write documentation, create a landing page for your account or organization and create unlimited project sites for you and your projects.

Websites, blogs, landing pages, live demos.

Things are hosted directly from your GitHub repo. So just edit, push and your changes are live (and under version control and easy collaboration with other team members).

You can generate a site using one of the pre-built themes or create a site from scratch.

Who is using GitHub Pages?

• Foundation - http://foundation.zurb.com/
• Twitter bootstrap - http://getbootstrap.com/
• Yeoman - http://yeoman.io/
• Octopress - http://octopress.org/
• many others

We'll cover these topics in this article:

• type of sites you can build with GitHub Pages
• user or organization site
• project site
• site generation methods
• pre-built themes
• from scratch
• advanced blogging tools (with Jekyll)

User or organization site from scratch (master)

You can create your personal page or organization site for free.

First: create a new repository named username.github.io, where username is your username (or organization name) on GitHub.

Then clone your repo:

$ git clone https://github.com/username/username.github.io
$ cd username.github.io

Create a demo hello world page:

$ echo "Hello World" > index.html

Push:

$ git add --all
$ git commit -m "Initial commit"
$ git push

Visit your page (you'll have to wait a bit the very first time you update your site):

• http://username.github.io

Project site (gh-pages branch)

For Project sites, you have the option to generate a site with one of the available pre-built themes, or to create a site from scratch.

Generate a site (pre-built themes)

Go to the settings panel of you repository and click on the Automatic Page Generator.

You can use the editor to add content and then pick a theme and publish!

Start from scratch

Follow this guide:

• https://help.github.com/articles/creating-project-pages-manually/

Jekyll

GitHub pages can be used in conjunction with Jekyll http://jekyllrb.com/.

What you can do with Jekyll:

"""Using Jekyll, you can blog using beautiful Markdown syntax, and without having to deal with any databases.

One of Jekyll’s best aspects is that it is “blog aware”. What does this mean, exactly? Well, simply put, it means that blogging is baked into Jekyll’s functionality. If you write articles and publish them online, this means that you can publish and maintain a blog simply by managing a folder of text-files on your computer. Compared to the hassle of configuring and maintaining databases and web-based CMS systems, this will be a welcome change!"""

Here you can find some useful resources about Jekyll and GitHub Pages:

• https://help.github.com/articles/using-jekyll-with-pages/ 
• https://help.github.com/articles/troubleshooting-github-pages-build-failures/

Prerequisites: Ruby. Your Ruby version should begin with 1.9.3 or 2.0.0.

User or organization site

Bootstrap a new dir name USER_OR_ORGANIZATION.github.io: 

$ jekyll new USER_OR_ORGANIZATION.github.io
$ cd USER_OR_ORGANIZATION.github.io

Basically you'll have to install Jekyll and Bundle as suggested on the GitHub official doc. Create a Gemfile file with this content:

source 'https://rubygems.org'
gem 'github-pages'

Check your url and baseurl options of your _config.yml file.
_config.yml for a project/repository site:
        ...
        baseurl: "/REPOSITORY" # the subpath of your site, e.g. /blog/
        url: "http://USER_OR_ORGANIZATION.github.io" # the base hostname & protocol for your site

Invoke Jekyll with Bundler:

$ bundle install
$ bundle exec jekyll build

The .gitignore file is already generated.

Now you can create the repo online on github and push your contents (.gitignore file already generated). Before pushing it is suggested to run Jekyll locally:

$ bundle exec jekyll serve

Result:

Now you can add new posts, change your page title, etc. See the _config.yml dir, the _posts dir and the official documentation online.

Now you can push your changes and they will display online.

Repo/Project site (with Jekyll)

You should create a gh-pages branch of your repository.

Follow this guide:

• https://help.github.com/articles/creating-project-pages-manually/

but instead of putting plain html files, initialize your branch with Jekyll (with bundle exec jekyll new .).

And then check your _config.yml. The user/organization site requires a different setup:
        ...
        baseurl: "" # the subpath of your site, e.g. /blog/
        baseurl: "/REPOSITORY" # the subpath of your site, e.g. /blog/
        url: "http://USER_OR_ORGANIZATION.github.io" # the base hostname & protocol for your site

Now you can build things and upload to GitHub. Results will displayed on http://USER_OR_ORGANIZATION.github.io/REPOSITORY.

Jekyll troubleshooting

Error 1 (LoadError):

/var/lib/gems/1.9.1/gems/jekyll-2.5.1/bin/jekyll:21:in `block in <top (required)>': cannot load such file -- jekyll/version (LoadError)

Solution (see https://github.com/jekyll/jekyll/issues/3084):

$ bundle exec jekyll COMMAND ("serve" or "new .")

Error 2 (Gemfile does not exist and directory is not empty)

I got two strange errors initializing an empty dir with Jekyll with the "bundle exec jekyll new ." command. Something like "error: Gemfile does not exist". Ok, let's create a Gemfile and "error: directory is not empty". If worked for me "bundle exec jekyll new USER_OR_ORGANIZATION.github.io"