To get ready for this workshop, please create a free GitHub account if you do not have one already. That is all you really need!
This workshop introduces GitHub Pages using GitHub’s web interface, demonstrating several ways to create gh-pages without using Jekyll locally. Basic familiarity with the GitHub web interface and HTML will be helpful. For quick introductions check out GitHub’s Hello World guide and w3schools HTML Tutorial.
Optional Prep [optional!]
For more advanced uses of GitHub Pages and Jekyll you will want a text editor, Git, Ruby, and Jekyll installed on your computer. The instructions below will set up your local development environment and provide a bit of background.
When working with code you should have a good text editor. Word processors such as MS Word can not be used to create or edit code. 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:
Git is a free, distributed version control system, a piece of software on your computer. GitHub is a Git repository hosting service, a place to store and sync your work in the cloud. Your GitHub Pages projects will be under Git version control, so you need the software on your machine.
Installing it is pretty straightforward:
- Windows: install Git for Windows using the default options, except when setup asks you to choose the default editor used by Git, select “Use the Nano editor by default”. This will give you Git, Git Bash, and Git GUI. Git Bash is a great terminal that lets you use UNIX style commands and utilities on Windows.
- Mac: check if Git is already installed by opening terminal and typing
git --version. If you do not have it, your system will often prompt you to install “Xcode Command Line Tools”–follow the prompt as this package is necessary for Ruby as well. Alternatively, type
xcode-select --installto start the process. If you want a newer version, download the official Mac git installer or use Homebrew.
- Linux: 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.
Frustratingly, different versions have many dependency and incompatibility problems. Because of these issues, many use Ruby Managers, such as RVM, to install and 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.5.0 or higher.
- Windows: Use RubyInstaller for Windows.
- First, download the suggested stable version “WITH DEVKIT” (as of this writing, Ruby+Devkit 2.7.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. The installer will proceed through a bunch of steps outputting a bunch of text in the terminal window–eventually, this will conclude and you should see a message with success in it. If the window doesn’t close, press Enter again or manually close it. (The installer can be restarted by typing
ridk installinto a command prompt)
- Mac: OS X has a version of Ruby installed by default. Check the version with
ruby -v. If it is > 2.5.0 you can use the system Ruby.
- 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. Check
ruby -vto make sure the repository version is > 2.5.0. See the official Jekyll Ubuntu install docs for more details.
Note: Jekyll does not officially support Windows, however it is cross platform and works fine (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 (on Windows it may appear as if nothing is happening, but be patient!).
Note: Linux users may need to
sudo, to avoid this install Ruby using RVM or add a gem install directory to
.bashrc. On Windows, if
gemreturns 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.rbin the directory.