Skip to content

Instantly share code, notes, and snippets.

@evanwill

evanwill/setup-jekyll-workshop.md

Created April 18, 2017 18:50
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save evanwill/56a894d0677597529b1e53aff5dcd5aa to your computer and use it in GitHub Desktop.
Save evanwill/56a894d0677597529b1e53aff5dcd5aa to your computer and use it in GitHub Desktop.
Download ZIP
prep for jekyll workshop
Raw
setup-jekyll-workshop.md

Build a Website with Jekyll and GitHub Pages

Workshop Prep

To get ready for this workshop, please create a free GitHub account if you do not have one already. Basic familiarity with the GitHub web interface and Git will be helpful. Check out GitHub's hello world guide and Try Git.

Local Jekyll Setup

The workshop will introduce several ways to create gh-pages without using Jekyll locally. However, if you would like to do development with Jekyll on your laptop, it is necessary to install Git, Ruby, and Jekyll.

Install Git

  • Windows: install Git for Windows using the default options. This will give you Git, Git Bash, and Git GUI. Git Bash is a great terminal that lets you use UNIX style commands on Windows.
  • Mac: check if Git is already installed by opening terminal and typing git --version. If you do not have it, download the official Mac installer.
  • Linux: install from your distribution's software center or package manager (for Ubuntu sudo apt-get install git).

If you are interested in using a visual GUI application integrated with GitHub, Windows and Mac users should also install GitHub Desktop using the default options. You can install GitHub Desktop in addition to other versions of Git.

There are other GUI apps available for managing and visualizing Git repositories, including Linux options.

Install Ruby

Ruby is a fairly young and developing language with some unique features. To use Jekyll, you do not need to know anything about Ruby, but if you are curious, check out Ruby in 20 minutes. Frustratingly, different versions have many dependency and incompatibility problems. Because of these issues, many use Ruby Managers, such as RVM, to switch between versions. However, if you are just interested in working with Jekyll, using an installer for your OS should be sufficient.

  • Windows: Use RubyInstaller for Windows.
    • First, download the most recent 32-bit version and double click to install. Use the install defaults, but make sure “Add Ruby executables to your PATH” is checked.
    • Second, from the same download page, download the Development Kit for the Ruby version you installed. Double click the DevKit file to extract, saving it to a permanent location, such as C:\rubyDevKit. Then open the directory in a terminal and run the commands ruby dk.rb init and ruby dk.rb install.
  • Mac: Use Homebrew, brew install ruby
  • Linux: Even though the version will not be the most up-to-date, use your distro's repositories. For example on Ubuntu, sudo apt-get install ruby-full. Make sure your version is > 2.0.

Install Jekyll

Note: Jekyll does not officially support Windows, however it is cross platform (they just don’t officially write windows documentation or check for bugs). There is a Jekyll on Windows page, but it is out of date. Not everything mentioned is required any more.

Jekyll is a Ruby Gem, a software package installed via Ruby's management system called RubyGems (similar to Python's pip). Open a terminal and type: gem install jekyll bundler

Note: Linux users may need to sudo. This might take a minute as Gem installs all the dependencies.

On Windows, if gem returns an error about secure connections, it may be necessary to update to a newer version of RubyGems as some versions had out of date SSL certificates. Manually install the newer version by downloading the zip package. Unzip the package, then run ruby setup.rb.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment