Jekyll Tutorial

23 Oct 2018

Last weekend I decided to give my outdated personal website an update and ended up trying out Jekyll. I was pleasantly surprised with Jekyll’s ease of use and integration with Github pages. I figured I’d pass along my experience to assist anyone else interested in trying out Jekyll with Github pages.

Table of Contents

  1. Jekyll Setup and Installation
  2. Using Jekyll with GitHub Pages
  3. Jekyll Common Additions

Jekyll Setup and Installation

  1. rbenv installation

    To install rbenv, follow the installation instructions on github. rbenv installation is a quick process when you’re using linux and when properly installed even provides tab-completion for the various rbenv commands.

  2. Install ruby

    Using rbenv I installed ruby version 2.5.3

    rbenv install 2.5.3
    
  3. Switch to your working directory

    mkdir -vp ~/src/my-jekyll-website
    cd ~/src/my-jekyll-website
    
  4. Set the local ruby version to your newly installed rbenv ruby version

    rbenv local 2.5.3
    
  5. Install Jekyll

    gem install jekyll bundler
    
  6. Jekyll walkthrough

    I would recommend going through the walkthrough on Jekyll’s website if you are new to Jekyll. The walkthough moves fairly quickly and explains all of the basic concepts of Jekyll really well.

Using Jekyll with GitHub Pages

Using Jekyll with GitHub Pages is an easy way to statically host a website. I’ve included below the steps to create a new Jekyll website to be hosted on GitHub Pages.

  1. Create a new Jekyll website

    jekyll new test_website
    
  2. Move into the new website directory

    cd test_website
    
  3. Initialize a git repository

    git init
    
  4. Create a .gitignore file and add a line for the _site directory

    vi .gitignore
    

    The _site directory is automatically generated by GitHub from the markdown and html files included in the main project directory and does not need to be included in the repository.

  5. Track the project files and push them to the GitHub repository

    For a user page:

    git remote add origin your-github-repo
    git add .
    git commit -m 'Initial commit'
    git push
    

    For a project page:

    git remote add origin your-github-repo
    git checkout -b gh-pages
    git add .
    git commit -m 'Initial gh-pages commit'
    git push
    
  6. Visit the newly created site

    For a user page:

    http(s)://<username>.github.io/
    

    For a project page:

    http(s)://<username>.github.io/<projectname>
    

    or

    Run the page locally

    bundle exec jekyll serve
    

    and visit http://127.0.0.1:4000

Jekyll Common Additions

Comments

Comments can be added to a static site using a comment service like disqus or just-comments. I decided to use disqus on my site and have been happy with the service.

Themes

GitHub pages supports integration of certain themes without including the layouts and assets from the theme.

These themes can be selected and tested by adding a line to _config.yml specifying the theme you wish to use.

ex.

theme: jekyll-theme-cayman

The available Jekyll themes can be found in the project’s Gemfile.lock file. Search for the prefix jekyll-theme- to see what is available for use.

Google Analytics Integration

Most themes support adding Google Analytics. While it varies from theme to theme, the Google Analytics identifier is usually specified in _config.yml as a variable like in the example below for the cayman theme.

ex.

google_analytics: UA-XXXXXXXX-X