Building and Maintaining a Jekyll Site

I first started using Jekyll a static site generator, early 2016.

The following isn’t a guide for how to use Jekyll, but instead almost a guide for me to quickly make updates to this site, and learn/document things on the way.

Content

To learn how Jekyll works I read, or more realistically skimmed over tutorials. However, what helped me the most was reverse engineering sites generated using Jekyll. Before that I tried using themes that people had created but many of them felt broken.

Posts for Nearly Everything

Within each blog post there is a YAML front matter block that will be processed by Jekyll as a special file. In order to communicate to Jekyll add three dashes before and after the front matter. Below is an example:

---
layout: article
title: "How I'm using Jekyll for this site."
excerpt: "Documenting my approach to using and learning Jekyll."
categories: blog
tags: [Jekyll, web development, style guide]
image:
  header: testfeature.png
  teaser: doggyrobes.jpg
featured: true
modified: 2016-06-15
---

Pages for Everything Else

Content that doesn’t need to be ordered chronologically or grouped in any way becomes a page. To keep things nice and tidy I place all of the source .md or .html files into a _pages directory and assign permalink overrides in the YAML Front Matter of each.

An architecture like this helps centralize the content so you’re not poking around trying to locate files. Meaningfully naming files should be the goal. Avoid patterns like /about/index.md as it makes distinguishing between multiple index.md files harder.

project-name/
├── _assets/
├── _includes/
├── _layouts/
├── _pages/
|   ├── 404.md
|   ├── about.md
|   ├── blog.md
|   ├── home.md
|   ├── portfolio.md
|   ├── resume.md
|   ├── sitemap.md
|   └── tag.md
├── _posts/
├── images
├── _config.yml
└── Gemfile

Tools Needed to Get the Site Up and Running

Installing Ruby, Bundler, and Ruby Gems are essential to getting this site running.

Bundler

It didn’t take long to fully embrace Bundler but mainly because it’s what everyone else is doing. Bundler is the official way to install Jekyll. Tt wasn’t that big of a leap for me to start using a Gemfile to manage all dependencies. To do that:

  1. Run bundle init to create an empty Gemfile
  2. Add gem 'jekyll' and any other gems to the Gemfile.

Below is what the gemfile for this site looked like as of 6/29/2017.

#Gemfile
source 'https://rubygems.org'

gem 'wdm', '~> 0.1.0' if Gem.win_platform?
gem 'mini_magick'
gem 'autoprefixer-rails'
gem 'uglifier'

# Jekyll
gem 'jekyll'
gem 'jekyll-archives'
gem 'jekyll-tagging-related_posts'
gem 'jekyll-sitemap'

Now when running bundle install each of the gems specified above are installed and a Gemfile.lock is created listing all of the dependencies.

In my experience it is extremely easy to break a gem resulting in the entire site to stop working. In other words (I know it’s obvious) but backup this file before installing a new update.

bundle exec jekyll serve
bundle exec jekyll build