jekyll Hosting GitHub Pages

Example

GitHub offers unlimited hosting for users or organizations and project site. Both Jekyll and static files are available.

Here are the steps in hosting your Jekyll blog on Github.

Setup

Users or organizations site

1. Create a repository named username.github.io, where username is your username (or organization name) on GitHub.
2. Clone the repository onto your computer:

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

3. Enter the project folder, bootstrap, design and debug your site:

   $ cd username.github.io
   $ bundle install
   $ bundle exec jekyll serve
   

4. Commit and push the repository:

   $ git add --all
   $ git commit -m "Initial commit"
   $ git push -u origin master
   

Now you should be able to go to username.github.io to see your blog.

Project site

Project site can be enabled in every repository including private repositories.

1. Enable project site.

   Go to Settings-GitHub Pages-Sources, choose a source to switch on GitHub Pages for the repository.

2. Build site

   You may build a Jekyll site from scratch or use Theme Chooser to find a theme for your project site.

3. Edit content

4. Commit

Now you should be able to go to username.github.io/your-project to see your project site.

Custom Domains

1. Open Settings->GitHub Pages->Custom domain, add your custom domain.
2. Create a CNAME file:

   $ cd username.github.io
   $ echo "example.com" > CNAME
   

3. Commit and push

   $ git commit -m "Add CNAME" CNAME
   $ git push -u origin master
   

Restrictions

Plugins

Jekyll has a plugin system with hooks that allow you to create custom generated content specific to your site. However, GitHub Pages only allows a white list of plugins for security reasons.

Here is the white list:

• Jekyll Sitemap
• Jekyll SEO Tag
• github-metadata
• Jekyll Feed
• Jekyll Redirect From
• Jemoji
• Jekyll Mentions

To avoid the inconsistency with GitHub Pages, you may use --safe to serve in local.

You can still use all plugins by publishing your generated site to GitHub Pages, by converting the site locally and pushing the generated static files to your GitHub repository instead of the Jekyll source files.

Markdown Engine

Since 01/05/2016, GitHub Pages supports only kramdown as Markdown engine.

See https://github.com/blog/2100-github-pages-now-faster-and-simpler-with-jekyll-3-0 for more detail.

Sources

GitHub allows you to set Jekyll sources to either master branch, gh-pages branch or /docs folder in master branch.

A full tutorial is available at https://pages.github.com/