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?"
Top 5 most common Jekyll hurdles starting out:
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)
Understanding site structure
GUI lacking (command line interface scares some users)
"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).
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.
The lack of documentation surrounding the site payload and methods available to the various objects. It took some digging to write my first plugin.
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)
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).
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.
Dealing with silent/undescriptive errors with liquid. Though, the majority of those seem to be remedied in later versions.
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.
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.
Installing it on a Windows machine. Adding Search functionality. Incorporating Tags to posts.
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.
It was the data folder, though now that's not a problem.
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.
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.