Creating A GitHub Page with Jekyll
This guide will help you create a static site on GitHub Pages using Jekyll with syntax highlighting support using Rogue and a custom domain.
Initial Repository Configuration
GitHub Pages can be used either at a user or project level. For user pages, create a GitHub repository named <your_username>.github.io. For project pages, create a branch in your GitHub repository called gh-pages.
Install Jekyll
Note: At the time of writing, for Jekyll v2 you need Ruby >= v1.9.3, and for Jekyll v3 you need Ruby >= v2.
Install Jekyll from Rubygems:
$ gem install jekyll
Note: Cygwin users on Windows may need to set aliases to make ruby binaries accessible by scripts. Add the following to your .profile:
alias gem='gem.bat'
alias rake='rake.bat'
alias erb='erb.bat'
alias irb='irb.bat'
alias rdoc='rdoc.bat'
alias ri='ri.bat'
alias rspec='rspec.bat'
alias cucumber='cucumber.bat'
alias bundle='bundle.bat'
Please see the official documentation for more information.
Scaffolding Your Site
Navigate to the root of your repository. If this is a project page, delete all existing files in your gh_pages branch and make a quick commit.
Create the initial site scaffolding:
$ jekyll new .
Test the site to make sure the initial scaffolding generation was successful. The following command will serve your Jekyll site while watching for and building changes as you make them:
$ jekyll serve --watch
Enable Syntax Highlighting with Rouge
Install Rouge from Rubygems:
$ gem install rouge
Create a file at the root of the repository named _config.yml and add the following:
markdown: kramdown
kramdown:
input: GFM
syntax_highlighter: rouge
All that is left is to generate the syntax highlighting stylesheet with rouge. There are a few themes available.
$ rougify style molokai >> stylesheets/syntax.css
Include this in the header tag of your index.html file:
<head>
<!-- ... -->
<link href="/stylesheets/syntax.css" rel="stylesheet">
<!-- ... -->
</head>
Add a Custom Domain
Add a custom domain to your project by creating a CNAME file at the root of your repository that contains the domain name you want. For example:
www.example.com
Make sure to add a CNAME entry for your domain pointing to <your_username>.github.io.
Please see the official documentation for more information.