5 common Jekyll traps for beginners (and help to overcome them!)

by Sam Bonney

Blog | Jekyll | 5 common Jekyll traps for beginners (and help to overcome them!) March 13, 2015

I recently reached out to people that I consider to be influencers in the Jekyll community. I asked them to share their opinions and experiences of Jekyll. Last week I shared their top 5 most common reasons for loving Jekyll.

The natural follow up question to 'what works?' is 'what doesn't?'. But I didn't want to ask that question - it's rather un-constructive. Instead I think new users might be more encouraged to hear the initial hurdles other users have overcome to get started. If they can overcome their's so might you Jekyll padawan!

So without further ado*…

*and remembering that some users began years ago and the Jekyll dev's have been doing a great job of fixing these issues or have plans to.

My second big survey question was "What was the first roadblock/hurdle/facepalm moment you had to overcome to begin using Jekyll?"

The TL;DR:

Top 5 most common Jekyll hurdles starting out:

  1. Initial setup is a pain (getting dev environment just right)
  2. Understanding site structure
  3. Windows support
  4. Compile speed
  5. GUI lacking (command line interface scares some users)

Help for getting through these initial Jekyll issues:

Identifying shared initial frustrations with Jekyll might make you feel better about encountering them. Better than a problem shared though is a problem solved! Below is a collection of info on identified issues:

Initial setup is a pain (getting dev environment just right)

  1. The Jekyll Core Team is putting lots of effort into making local installs easier. Have your say on a solution
  2. Watch Travis Neilson's AWESOME intro video for local installation.
  3. Move your compile to the cloud. See CloudCannon notes below.

Understanding site structure

  1. The Jekyll docs do cover this well so give them another read.
  2. Andrew Munsell's Jekyll by Example tutorial gives a great overview of concepts in action.
  3. Another alternative for a fully explained build is the older Yes We Jekyll. (16/3 suggested by @parkr)
  4. If the powerful 'collections' feature is confusing you check out this recent guide by @BenBalter: Explain like I’m five: Jekyll collections. (16/3 great suggestion by @AlWillis)

Windows support

  1. This is the official-unofficial guide by @juthilo

Compile speed

  1. Not a lot of quick wins available here at the moment, but it has been and is a top priority for the Jekyll Core Team. In fact in the latest Jekyll 3.0.0 beta release notes incremental regeneration is item number one.

GUI lacking (command line interface scares some users)

  1. Prose.io is a solution that some Jekyll users have turned to to assist with editing markdown and the publishing process.
  2. CloudCannon is looking to nail this! See below.

In their own words:

"What was the first roadblock/hurdle/facepalm moment you had to overcome to begin using Jekyll?"

Porting WordPress content over. Luckily there are/were a number of open-source tools to help me, but it wasn’t necessarily simple, and brought a fairly long-tail of legacy with it (code blocks incorrectly formatted, WP meta data being crammed into Jekyll’s YML front matter).

Harry Roberts

Jekyll blog post

With over 1,000 blog posts on my site when I moved from WordPress to Jekyll, it takes some time to generate my site. That was a minor annoyance which has gotten better over the years with faster computers and more performant Jekyll updates.

Paul Stamatiou

WordPress to Jekyll blog post

The lack of documentation surrounding the site payload and methods available to the various objects. It took some digging to write my first plugin.

Brett Terpstra

Jekyll CDN blog post

The setup is kind of hard with the ruby dependencies/rvm/gemfiles/gem bundles. Now there are some decent guides I guess but when I was starting there was no solid guide to explain how it worked, there was a lot of assumed knowledge from being a Ruby developer even though I used Jekyll as a web designer. Setting Jekyll up in Windows is also painful on its own (I don't use Windows primarily but used Jekyll in a coding workshop I gave, not everyone has a Mac)

Johan Ronsse

Intro to Jekyll video

Well, there's Jekyll, and then there's GitHub Pages Jekyll. Jekyll itself is pretty straightforward, but GitHub Pages doesn't have great error messaging on build fail. It has gotten a bit better over the years, but still... Jekyll itself was pretty easy to work with once you figured out the basic config setup (which, if you've never used a config file before, takes a little learning, but not too bad).

Michelle Hertzfeld

Using Jekyll and GitHub, Tips for Designers

Getting my Ruby environment setup and figuring out problems with gems and other dependencies installing. Jekyll was straightforward enough, it was all the mess that comes with Ruby that wasn't.

Michael Rose

Jekyll themes

Dealing with silent/undescriptive errors with liquid. Though, the majority of those seem to be remedied in later versions.

John Otander

Jekyll Pixyll theme

Using Jekyll was the first time I had to use the terminal. I am a designer first, and that tends to scare our kind, but its not so bad. Another thing was trying to get my dev environment perfect. But now Jekyll handles SASS and there is an adequate Jade plugin.

Travis Neilson

DevTips "Jon doesn't like Jekyll" video

Local installation. You know that Steve Jobs quote from an Apple Q&A; "if you see a stylus, they blew it." I have that feeling with platforms that pertain to be user friendly, but the install process involves dicking around with the terminal prompt.

Adam Wilcox

Podcasting with Jekyll tutorial

Installing it on a Windows machine. Adding Search functionality. Incorporating Tags to posts.

Richard Bray

Muffin Jekyll theme

Getting the file structure right. Figuring out how to get the index page to paginate through posts. Using an .html extension instead of .md and being confused about why the translation didn't happen.

Alan W. Smith

Date formatting in Jekyll

It was the data folder, though now that's not a problem.

David Zvenyach

Jekyll data_source tutorial

I haven't run into any major hurdles lately, most of the growing pains came from just trying to get a firm grasp on the basics. Does Jekyll process a page through Markdown or Liquid first? Why can't I use Liquid tags in excerpts? Why can't I specify a permalink in my blog index front-matter? The documentation for Jekyll is great, but some things just need to be learned through experimentation.

Mike Greiling

Jekyll intro tutorial

Plug from CloudCannon:

Avoid the initial Jekyll environment setup by moving your compilation to the cloud. Add non-tech friendly GUIs to your Jekyll workflow. Check out CloudCannon's Jekyll beta overview video and then join the beta.


Keep up to date with CloudCannon articles, tutorials, templates and other Jekyll news

Subscribe