Jekyll • Simple, blog-aware, static sites

Jekyll 3.6.2 Released

2017-10-21T12:31:40-07:00

3.6.2 is out, it’s a tiny patch release and we invite you to run bundle update if you want to avoid possible build problems with:

some UTF-8 and UTF-16 encoded files,
fully numeric layout names (we convert those to string for you now).

Other changes include updates to our documentation, like this complete video series by Giraffe Academy aimed at complete beginners. A big thanks to Mike for this.

And if you’re wondering what happened to version 3.6.1, it was just our new release maintainer getting familiar with the release process. 😄

We try to release patch releases as quickly as possible and we’re already working on the next minor version 3.7.0 that will allow you to store all your collections in a single directory. Stay tuned.

Theme developers are invited to test the brand new jekyll-remote-theme plugin and give their feedback to @benbalter. This plugin allows you to use any GitHub hosted theme as a remote theme!

Once again, many thanks to our contributors who helped make this release possible: ashmaroli, bellvat, Frank Taillandier, i-give-up, Jan Piotrowski, Maximiliano Kotvinsky, Oliver Steele and Pat Hawks. For some it was their first contribution to open-source 👏

As it’s been nine years this week that Tom Preston-Werner started this project, I also wanna seize this opportunity to thank all of the 732 contributors who helped make it possible for Jekyll to power millions of websites around the world today.

Happy Birthday Jekyll! 🎂

Diversity in Open Source, and Jekyll’s role in it

2017-10-19T12:33:00-07:00

Open Source has a problem with diversity. GitHub recently conducted a survey which revealed that 95% of the respondents were identifying as male. This is even worse than in the tech industry overall, where the percentage is only about 76%. Every other week, there seems to be another case of a maintainer engaging in targeted harassment against minorities. People somehow deem it completely okay to let these things slide, though.

Fortunately, there’s a couple of things we can do to make it easier and more comfortable for people that have never contributed to any open source project before, to contribute to our projects.

Add a Code of Conduct, and enforce it

This might seem like one of the easiest steps to do, but it actually requires a lot of dedication to pull through with. Basically, a Code of Conduct is a document detailing what is and what isn’t acceptable behavior in your project. A good Code of Conduct also details enforcement procedures, that means how the person violating the Code of Conduct gets dealt with. This is the point at which I’ve seen a looooot of projects fail. It’s easy enough to copy-paste a Code of Conduct into your project, but it’s more important to be clear on how to enforce it. Inconsistent —or worse, nonexistent— enforcement is just going to scare off newcomers even more!

The most widely adopted Code of Conduct is the Contributor Covenant. It’s a very good catch-all document, but it is a bit light in the enforcement section, so I’d recommend to flesh it out by yourself, be it by means of adding contact information or expanding the enforcement rules.

No matter which Code of Conduct you pick, the most important thing is to actually read it for yourself. The worst thing in open source is a maintainer that doesn’t know when they’ve violated their own Code of Conduct.

Document your contributing workflow

The problem that puts people off the most is incomplete or missing documentation, as revealed through GitHub’s open source survey. A very popular myth in programming is that good code explains itself, which might be true, but only for the person writing it. It’s important, especially once you put your project out there for the world to see, to document not only your code, but also the process by which you maintain it. Otherwise, it’s going to be extremely hard for newcomers to even figure out where to begin contributing to your project.

Jekyll has an entire section of its docs dedicated to information on how to contribute for this very reason. Every documentation page has a link to directly edit and improve it on GitHub. It’s also important to realize that not all contributions are code. It can be documentation, it can be reviewing pull requests, but it can also just be weighing into issues, and all of this should be recognized in the same way. At Jekyll, out of 397 total merged pull requests in the last year, 204 were documentation pull requests!

Create newcomer-friendly issues

For most people new to open source, the biggest hurdle is creating their first pull request. That’s why initiatives such as YourFirstPR and First Timers Only were started. Recently, a GitHub bot that automatically creates first-timer friendly issues was launched, which makes it very easy for maintainers to convert otherwise small or trivial changes into viable pull requests that can be taken on by newcomers! So we decided to give it a shot, and we’ve created a couple of very easy first timers only issues:

(There’s also an up-to-date listing of all of our first timers only issues here)

These issues are designed to be taken on only by someone who has had little to no exposure to contributing to open source before, and additionally, project maintainers offer support in case a question arises.

Jekyll is a very big and popular open source project, and we hope that with these special issues, we can help people who haven’t contributed to open source before to catch a footing in these unsteady waters.

Be nice

I know this is a cliche and a overused phrase, but really, it works if you pull through with it. Come to terms with the fact that some people aren’t as fast or reliable as you might want to think. Don’t get angry when a contributor takes a day longer than you might like them to. Treat new contributors to your project with respect, but also with hospitality. Think twice before you send that comment with slurs in it.

I’ve been contributing to open source for about 4 years now, and I’ve had my fair share of horrible, horrible experiences. But Jekyll has historically been a project that has always valued the people contributing to it over the code itself, and I hope we can keep it that way. I also hope that other project maintainers read this and take inspiration from this post. Every project should be more diverse.

Jekyll turns 3.6!

2017-09-21T13:38:20-07:00

Another much-anticipated release of Jekyll. This release comes with it Rouge 2 support, but note you can continue to use Rouge 1 if you’d prefer. We also now require Ruby 2.1.0 as 2.0.x is no longer supported by the Ruby team.

Otherwise, it’s a massive bug-fix release! A few bugs were found and squashed with our Drop implementation. We’re using the Schwartzian transform to speed up our custom sorting (thanks, Perl community!). We now protect against images that are named like posts and we generally worked on guarding our code to enforce requirements, instead of assuming the input was as expected.

Please let us know if you find any bugs! You can see the full history here.

Many thanks to our contributors who helped make this release possible: Aleksander Kuś, André Jaenisch, Antonio Argote, ashmaroli, Ben Balter, Bogdan, Bradley Meck, David Zhang, Florian Thomas, Frank Taillandier, Jordon Bedwell, Joshua Byrd, Kyle Zhao, lymaconsulting, Maciej Bembenista, Matt Sturgeon, Natanael Arndt, Ohad Schneider, Pat Hawks, Pedro Lamas, and Sid Verma.

As always, Happy Jekylling!

Jekyll 3.5.2 Released

2017-08-12T13:31:40-07:00

3.5.2 is out with 6 great bug fixes, most notably one which should dramatically speed up generation of your site! In testing #6266, jekyllrb.com generation when from 18 seconds down to 8! Here is the full line-up of fixes:

Backport #6266 for v3.5.x: Memoize the return value of Document#url (#6301)
Backport #6247 for v3.5.x: kramdown: symbolize keys in-place (#6303)
Backport #6281 for v3.5.x: Fix Drop#key? so it can handle a nil argument (#6288)
Backport #6280 for v3.5.x: Guard against type error in absolute_url (#6287)
Backport #6273 for v3.5.x: delegate StaticFile#to_json to StaticFile#to_liquid (#6302)
Backport #6226 for v3.5.x: Reader#read_directories: guard against an entry not being a directory (#6304

A full history is available for your perusal. As always, please file bugs if you encounter them! Opening a pull request with a failing test for your expected behaviour is the easiest way for us to address the issue since we have a reproducible example to test again. Short of that, please fill out our issue template to the best of your ability and we’ll try to get to it quickly!

Many thanks to our contributors without whom this release could not be possible: Ben Balter & Kyle Zhao.

Happy Jekylling!

Jekyll 3.5.1 Released

2017-07-17T09:40:37-07:00

We’ve released a few bugfixes in the form of v3.5.1 today:

Some plugins stopped functioning properly due to a NoMethodError for registers on NilClass. That’s been fixed.
A bug in relative_url when baseurl is nil caused URL’s to come out wrong. Squashed.
Static files’ liquid representations should now have all the keys you were expecting when serialized into JSON.

We apologize for the breakages! We’re working diligently to improve how we test our plugins with Jekyll core to prevent breakages in the future.

More details in the history. Many thanks to all the contributors to Jekyll v3.5.1: Adam Voss, ashmaroli, Ben Balter, Coby Chapple, Doug Beney, Fadhil, Florian Thomas, Frank Taillandier, James, jaybe, Joshua Byrd, Kevin Plattret, & Robert Jäschke.

Happy Jekylling!

Jekyll turns 3.5, oh my!

2017-06-15T14:32:32-07:00

Good news! Nearly 400 commits later, Jekyll 3.5.0 has been released into the wild. Some new shiny things you might want to test out:

Jekyll now uses Liquid 4, the latest! It comes with whitespace control, new filters concat and compact, loop performance improvements and many fixes
Themes can specify runtime dependencies (in their gemspecs) and we’ll require those. This makes it easier for theme writers to use plugins.
Speaking of themes, we’ll properly handle the discrepancy between a convertible file in the local site and a static file in the theme. Overriding a file locally now doesn’t matter if it’s convertible or static.
Pages, posts, and other documents can now access layout variables via {{ layout }}.
The gems key in the _config.yml is now plugins. This is backwards-compatible, as Jekyll will gracefully upgrade gems to plugins if you use the former.
Filters like sort now allow you to sort based on a subvalue, e.g. {% assign sorted = site.posts | sort: "image.alt_text" %}.
You can now create tab-separated data files.
Using layout: none will now produce a file with no layout. Equivalent to layout: null, with the exception that none is a truthy value and won’t be overwritten by front matter defaults.
No more pesky errors if your URL contains a colon (sorry about those!)
We now automatically exclude the Gemfile from the site manifest when compiling your site. No more _site/Gemfile!
We fixed a bug where abbreviated post dates were ignored, e.g. _posts/2016-4-4-april-fourth.md.

And so much more!

There was a huge amount of effort put into this release by our maintainers, especially @pathawks, @DirtyF, and @pup. Huge thanks to them for ushering this release along and keeping the contributions flowing! Jekyll wouldn’t work without the tireless dedication of our team captains & maintainers. Thank you, all!

A huge thanks as well to our contributors to this release: Adam Hollett, Aleksander Kuś, Alfred Myers, Anatoliy Yastreb, Antonio Argote, Ashton Hellwig, Ashwin Maroli, Ben Balter, BlueberryFoxtrot, Brent Yi, Chris Finazzo, Christoph Päper, Christopher League, Chun Fei Lung, Colin, David Zhang, Eric Leong, Finn Ellis, Florian Thomas, Frank Taillandier, Hendrik Schneider, Henry Kobin, Ivan Storck, Jakub Klímek, Jan Pobořil, Jeff Puckett, Jonathan Hooper, Kaligule, Kevin Funk, Krzysztof Szafranek, Liu Cheng, Lukasz Brodowski, Marc Bruins, Marcelo Canina, Martin Desrumaux, Mer, Nate, Oreonax, Parker Moore, Pat Hawks, Pedro Lamas, Phil Nash, Ricardo N Feliciano, Ricky Han, Roger Sheen, Ryan Lue, Ryan Streur, Shane Neuville, Sven Meyer, Tom Johnson, William Entriken, Yury V. Zaytsev, Zarino Zappia, dyang, jekylltools, sean delaney, zenHeart

Please file any bugs with detailed replication instructions if you find any bugs. Better yet, submit a patch if you find the bug in the code and know how to fix it! :heart:

Happy Jekylling! :tada:

Jekyll 3.4.3 Released

2017-03-21T06:52:53-07:00

Another one-PR patch update as we continue our quest to destroy all bugs. A fairly technical debriefing follows, but the TLDR is that we have updated the uri_escape filter to more closely follow the pre-v3.4.0 behavior.

In v3.4.0, we moved away from using the deprecated URI.escape in favor of Addressable::URI.encode. This is what powers our uri_escape filter.

While this transition was mostly a smooth one, the two methods are not identical. While URI.escape was happy to escape any string, Addressable::URI.encode first turns the string into an Addressable::URI object, and will then escape each component of that object. In most cases, this difference was insignificant, but there were a few cases where this caused some unintended regressions when encoding colons.

While Addressable can understand that something like "/example :page" is a relative URI, without the slash it cannot figure out how to turn "example :page" into an Addressable::URI object. URI.escape had no such objection. This lead to the following Liquid code working fine in Jekyll 3.3.x but breaking in 3.4.0:

{{ "example :page" | uri_escape }}

This was not an intended consequence of switching to Addressable.

Fortunately, the solution was not complicated. Addressable has a method Addressable::URI.normalize_component which will simply escape the characters in a string, much like URI.escape.

Thanks to @cameronmcefee and @FriesFlorian for reporting this issue.

Happy Jekylling!

Jekyll 3.4.2 Released

2017-03-09T12:41:57-08:00

Another one-PR patch update, though without the same lessons as for the previous release.

This release includes a beneficial change for a number of plugins: static files now respect front matter defaults.

You might be asking yourself: “why would static files, files that are static files explicitly because they don’t have YAML front matter, want to respect YAML front matter?” That’s a great question. Let me illustrate with an example.

Let’s look at jekyll-sitemap. This plugin generates a list of documents, pages, and static files, and some metadata for them in an XML file for a Google/Yahoo/Bing/DuckDuckGo crawler to consume. If you don’t want a given file in this list, you set sitemap: false in the YAML front matter. But what about static files, which don’t have YAML front matter? Before this release, they could not be excluded because they had no properties in YAML other than the ones we explicitly assigned. So if you had a PDF you didn’t want to be in your sitemap, you couldn’t use jekyll-sitemap.

With this release, you can now set front matter defaults for static files:

defaults:
  -
    scope:
      path: "pdfs/"
    values:
      sitemap: false

Now, for every file in the Liquid site.static_files loop which is in the folder pdfs/, you’ll see sitemap equal to false.

Many thanks to @benbalter for coming up with the solution and ensuring sitemaps everywhere are filled with just the right content.

As always, if you notice any bugs, please search the issues and file one if you can’t find another related to your issue.

Happy Jekylling!

Jekyll 3.4.1, or “Unintended Consequences”

2017-03-02T11:20:26-08:00

Conformity is a confounding thing.

We write tests to ensure that a piece of functionality that works today will work tomorrow, as further modifications are made to the codebase. This is a principle of modern software development: every change must have a test to guard against regressions to the functionality implemented by that change.

And yet, occasionally, our very best efforts to test functionality will be thwarted. This is because of how our code produces unintended functionality, which naturally goes untested.

In our documentation, we tell users to name their posts with the following format:

YYYY-MM-DD-title.extension

That format specifies exactly four numbers for the year, e.g. 2017, two letters for the month, e.g. 03, and two letters for the day, e.g. 02. To match this, we had the following regular expression:

%r!^(?:.+/)*(\d+-\d+-\d+)-(.*)(\.[^.]+)$!

You might already see the punchline. While our documentation specifies the exact number of numbers that is required for each section of the date, our regular expression does not enforce this precision. What happens if a user doesn’t conform to our documentation?

We recently received a bug report that detailed how the following file was considered a post:

84093135-42842323-42000001-b890-136270f7e5f1.md

Of course! It matches the above regular expression, but doesn’t satisfy other requirements about those numbers being a valid date (unless you’re living in a world that has 43 million months, and 42 million (and one) days). So, we modified the regular expression to match our documentation:

%r!^(?:.+/)*(\d{4}-\d{2}-\d{2})-(.*)(\.[^.]+)$!

Our tests all passed and we were properly excluding this crazy date with 43 million months and days. This change shipped in Jekyll v3.4.0 and all was well.

Well, not so much.

A very common way to specify the month of February is 2. This is true for all single-digit months and days of the month. Notice anything about our first regular expression versus our second? The second regular expression imposes a minimum, as well as maximum, number of digits. This change made Jekyll ignore dates with single-digit days and months.

The first eight years of Jekyll’s existence had allowed single-digit days and months due to an imprecise regular expression. For some people, their entire blog was missing, and there were no errors that told them why.

After receiving a few bug reports, it became clear what had happened. Unintended functionality of the last eight years had been broken. Thus, v3.4.0 was broken for a non-negligible number of sites. With a test site in-hand from @andrewbanchich, I tracked it down to this regular expression and reintroduced a proper minimum number of digits for each segment:

%r!^(?:.+/)*(\d{2,4}-\d{1,2}-\d{1,2})-(.*)(\.[^.]+)$!

And, I wrote a test.

This change was quickly backported to v3.4.0 and here we are: releasing v3.4.1. It will fix the problem for all users who were using single-digit months and days.

With this, I encourage all of you to look at your code for unintended functionality and make a judgement call: if it’s allowed, should it be? If it should be allowed, make it intended functionality and test it! I know I’ll be looking at my code with much greater scrutiny going forward, looking for unintended consequences.

Many thanks to our Jekyll affinity team captains who helped out, including @pathawks, @pnn, and @DirtyF. Thanks, too, to @ashmaroli for reviewing my change with an eye for consistency and precision. This was certainly a team effort.

We hope Jekyll v3.4.1 brings your variable-digit dates back to their previous glory. We certainly won’t let that unintended functionality be unintended any longer.

As always, Happy Jekylling!

Jekyll turns 3.4.0

2017-01-18T11:19:13-08:00

Hey there! We have a quick update of Jekyll for you to enjoy this January. Packed full of bug fixes as usual, thanks to the tireless efforts of our exceptional Jekyll community. Three changes to call out:

If you’re a big fan of where_by_exp, you’ll be an even bigger fan of group_by_exp.
Using a custom timezone in Jekyll on Windows? Yeah, sorry that hasn’t ever worked properly. We made it possible to accurately set the timezone using IANA timezone codes.
Documentation has been improved, notably on themes, includes and permalinks.

And lots and lots more!

This update was made possible by the dedicated efforts of our excellent contributors: Ajay Karwal, Alexey Rogachev, Ashwin Maroli, BlueberryFoxtrot, Chase, Chayoung You, Dean Attali, Dmitrii Evdokimov, Don Denton, Eldritch Cheese, Fabrice Laporte, Florian Thomas, Frank Taillandier, Hugo, Ivan Dmitrievsky, Joel Meyer-Hamme, Josh Habdas, Kenton Hansen, Kevin Wojniak, Kurt Anderson, Longwelwind, Max Chadwick, Nicolas Hoizey, Nursen, Parker Moore, Pat Hawks, Purplecarrot, Ricardo N Feliciano, Rob Crocombe, Roger Ogden, Skylar Challand, Thiago Arrais, Tim Banks, Tom Johnson, Tunghsiao Liu, XhmikosR, Zlatan Vasović, alexmalik, brainscript, kimbaudi, muratayusuke, penny, and yoostk.

As always, if you encounter bugs, please do search the issues and file an issue if you aren’t able to find a resolution. We also have our Jekyll Talk forum for those of you with general questions about how to accomplish certain tasks with Jekyll.

We have some exciting updates in store for v3.5, and we’re hard at work on those already.

Happy Jekylling!