Workshop Prep

To create your own materials using workshop-template, please create a free GitHub account if you do not have one already. Basic familiarity with the GitHub web interface will be helpful.

For a quick introduction check out GitHub’s Hello World guide and Try Git.

It is possible to create a website with this template using only GitHub’s web interface–it works great! However, for more advanced uses you will want Git, Ruby, and Jekyll installed on your computer to do local development.

Have a GitHub account.
Fork or import this repository.
Optional: have Git, Jekyll, and a nice text editor installed.

Local Jekyll Setup [optional]

Install Git

Git is a free, distributed version control system. GitHub is a Git repository hosting service, a place to store and sync your work in the cloud–your Jekyll and GitHub Pages projects will be under Git version control, so you need the software on your machine.

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: check if Git is already installed by opening terminal and typing git --version. If you do not have it, install from your distribution’s software center or package manager (for Ubuntu sudo apt 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 programming 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. Jekyll requires a Ruby version > 2.2.5.

Windows: Use RubyInstaller for Windows.
- First, download the suggested stable version “WITH DEVKIT” (as of this writing, Ruby+Devkit 2.4.X (x64)) and double click to install. Use the install defaults, but make sure “Add Ruby executables to your PATH” is checked. On the final step, ensure the box to start the MSYS2 DevKit is checked.
- Second, the installer will open a terminal window with options to install MSYS2 DevKit components. Choose option 3, “MSYS2 and MINGW development toolchain”, or simply press ENTER to install all the necessary dependencies. (This installer can be restarted by typing ridk install into a command prompt)
Mac: OS X has a version of Ruby installed by default. Check the version with ruby -v. If it is > 2.2.5 you can use the system Ruby. However, a newer version can be installed using Homebrew, brew install ruby, or a manager such as rbenv or RVM. Check the official Jekyll Mac install docs for tips.
Linux: Even though the version will not be the most up-to-date, the simplest method is to use your distro’s repositories. For example on Ubuntu, sudo apt install ruby-full. Make sure the repository version is > 2.2.5. You will also need the build tools Make and GCC, on Ubuntu get them with sudo apt install build-essential. For a more up-to-date version, use a manager such as RVM.

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 can be out of date and inaccurate.

Jekyll is a 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

This will take a minute as Gem installs all the dependencies and builds extensions.

Note: Linux users may need to sudo, to avoid this install Ruby using RVM. 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 have out of date SSL certificates. Manually install the newer version by downloading the RubyGems zip package. Unzip the package, then run ruby setup.rb in the directory.

Text Editor

When working with code you should have a good text editor. Windows notepad does not handle UTF-8 encoding or UNIX line endings that are standard for cross platform applications. For basic editing, Windows Notepad++, Mac TextEdit, or Linux Gedit are sufficient. However, a more complete code editor will be helpful for managing Jekyll projects.

Open-source cross platform suggestions: