Developing with Jekyll

---

Development Environment

To work with Jekyll on your local machine you will need some software installed on your computer, including:

• A text editor
• Git
• Ruby (2.5 +)
• Jekyll

Getting everything set up can be a major hurdle, but stick with it! This environment will empower you to edit code, version control, manage your files, and create websites–so its pretty neat and rewarding.

Text Editor

When working with code you need 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. Try one of these open source, cross platform options:

• Visual Studio Code
• Atom

These editors will allow you to work on whole folders of files at once (i.e. your Jekyll project repository) and have built in helpers for using and visualization Git.

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 GitHub Pages projects will be under Git version control, so you need the software on your machine to work with it locally.

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: you will need “Xcode Command Line Tools” installed, so open a terminal (to find it search for “terminal” in Spotlight), type in the command xcode-select --install, and follow the prompts. After the install finishes, try typing git --version. If you want a newer version, 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 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.

Generally, it is easiest to start your project repository on GitHub, then clone the repository to your local machine to start working on it. This ensures your local copy is linked to the remote on GitHub.

Ruby

Ruby is a programming language popular with web applications. You do not need to know anything about Ruby, but you do need it to run Jekyll on your system! If you are curious to learn, check out Ruby in 20 minutes or Try Ruby in your browser.

Jekyll requires a Ruby version 2.5.0 or higher installed on your computer. Installing Ruby isn’t super easy, but Jekyll install docs have detailed guides for getting set up on different operating systems. Here is a short summary:

Jekyll

Jekyll is a Gem, a software package installed via Ruby’s management system called RubyGems (similar to Python’s Pip).

To install Jekyll, open a terminal and type:

gem install jekyll bundler

This will take a minute or two as Gem installs all the dependencies and builds extensions (on Windows it may appear as if nothing is happening, but be patient!). Jekyll is made up of dozens of other Ruby Gems, so Bundler is a helper to manage dependencies. If you are just using Ruby for Jekyll on smaller projects, you hopefully won’t have to deal with Bundler and the maze of dependencies! For more details see Jekyll’s Installation guides.

---

Start a Jekyll Project

As a demonstration, let’s create a basic Bootstrap website using an existing template. In this case we are not using Jekyll theme, instead all the “theme” files will be contained inside the repository. This makes it easier to customize than working with the Gem based theme system.

Overview:

1. Go to the bootstrap-template repository on GitHub.
2. Make your own copy of the code on GitHub by clicking the green “Use this template” button (alternatively use Import, or just download the code and copy the files into your own repo).
3. Clone your new repository to your local machine (using Git or GitHub Desktop, click the green “Code” button for the link).
4. Open the repository folder in your text editor.
5. Edit the _config.yml with your project info (i.e. edit title, description, year, and author for your project). Then Git Commit!
6. In the root of your repository, start a Terminal (or use one built into your text editor). Type the command jekyll s to start the development server. Copy the localhost URL it provides, paste into a private browser tab to view your site locally.
7. In the “pages” folder, edit the stubs in Markdown to create content (see bootstrap-template docs for options). And Git Commit!
8. Customize with Sass/CSS, edit “assets/css/main.scss”, “_sass/_custom.scss”, “_data/theme-colors.csv” (options built into bootstrap-template). And Git Commit!
9. When done, Git Commit all changes, and Git Push to GitHub.
10. Activate GitHub Pages in your repository’s Settings.
11. Enjoy website!

---