Resolving Jekyll 3 Draft Issues

I was going to write a sweet blog post, and thought that I would quickly add footnotes support to my blog. I use the Redcarpet gem for this blog, and it appears to have support for footnotes. I tried adding the footnotes setting to the Redcarpet configuration, but that didn’t work. I figured that I had an old version of Redcarpet, so I wanted to upgrade it. Unfortunately, my Jekyll version was a little out of date (1.5.1, where the most recent is 3.0.2.)

I figured it wouldn’t be too painful to upgrade. For the most part, upgrading was straightforward. However–I ran into an issue where my drafts were not showing when I ran the jekyll build --drafts command (or its serve counterpart.) It ended up taking me several hours to debug, so I figured I’d share in case someone else runs into a similar issue.

I started making significant headway when I created a new project with the same Jekyll version (3.0.2). I created one simple draft in that project, ran the command, and the draft was correctly generated into my _site folder. I copied over only my _config.yml file (after trying to copy a few other things), and the draft was not correctly generated. So it had to be something with my configuration file.

I ended up commenting out various parts of the file until the file was properly generated, and found the bad line:

# Files to exclude from copying to _site when the site is built
  - Gemfile
  - Gemfile.lock
  - Guardfile
  - README.markdown
  - _drafts  # <<< the offending line
  - _reference
  - ..etc.

Apparently excluding the _drafts folder doesn’t work so well with newer versions of Jekyll. Previously it was excluded (I think) so that I didn’t deploy my _drafts folder. My guess is that since it is excluded from being copied, it is not present for some downstream process. It would have been nice to get a warning about this behavior though.

I tried it out on my blog, and… it still didn’t show my drafts! I quickly compared the two versions and my blog’s drafts had published: false set to true. So I figured that removing this line would make a difference, and it did. I guess that older versions of Jekyll must have ignored this flag when --drafts was passed, but it seems like newer versions of Jekyll take the published flag into consideration. I removed it from all of my drafts and the scripts that generate drafts and pages and posts.

Now it seems to work. It only took me like four hours.

So instead of the sweet blog post, I wrote this up instead. Hope it helps! 1, 2, 3

  1. These footnotes probably weren’t worth it… 

  2. But since I have them now, I am going to gratuitously use them. 

  3. Multi-line support is a bit complicated. 

    I wrote up how I currently work around multi-line footnotes with Redcarpet on a Github issue. It is slightly suboptimal due to the return link being on the first paragraph, but overall seems to work.

Categories: main

« Blocking Your Own Damn Distractions Rice Bucket Workout: Forearm and Grip For Ultimate »