(Update: 3/8/2022) This post is outdated.

I’ve been through the process of setting up jekyll in the past. If it’s been over a year since I made a post, then I invariably forget how it all works and end up spending at least 15 minutes reading the basic tutorials for setting up ruby, jekyll, github-pages, and how to test the blog locally.

Rather than repeat this process, I’m laying out the steps here to save time for future me. This assumes the blog has been created, but if starting from scratch, then the main GitHub pages site will get you up and running quickly. This mostly follows along with “Setting up your GitHub Pages site locally with Jekyll”.

Install packages

Create a file named `Gemfile1 in the root dir of the site with the following:

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins

Install required packages (Fedora 23):

dnf install ruby-devel
dnf install nodejs
gem install bundler
bundle install --binstubs ~/.gem/ruby/bin

Install required packages (Ubuntu 16.04):

apt-get install ruby-dev
apt-get install nodejs
apt-get install bundler
bundle install --binstubs ~/.gem/ruby/bin

Note: Don’t use gem install github-pages. There were issues related to markdown formatting.

Add the locally installed gems to the shell path by adding this to ~/.bashrc:

PATH="$(ruby -e 'print Gem.user_dir')/bin:$PATH"
export PATH

Test site locally

This command will serve up the site locally:

bundle exec jekyll serve --host=0.0.0.0

Open browser to http://localhost:4000 to view.

Write new posts

All posts go in the _posts directory, and must be named in the format YEAR-MONTH-DAY-title.md

For example: 2016-05-14-jekyll-setup.md

Each post should contain the following “front matter”:

---
title: This is my title
layout: post
---

Below that goes the contents of the post. GitHub-style markdown is supported. See here and here for cheatsheets and guides on syntax.