Jekyll Date Formatting Examples

Posted: October 01, 2013 - Updated: November 29, 2013

###Summary (tl;dr)

These examples provide tested code snippets for displaying several date formats on a Jekyll site1. They should also work on GitHub Pages, Shopify or anything else that uses Liquid. An alternate title for this post should be:

Everything you wanted to know about Jekyll date formatting but were afraid to ask.

If there are designs that use that format, they are few and far between. Creating friendlier looking dates is done by applying Liquid's "date:" filter. For example, the tag/filter combination:

{{ page.date | date: '%B %d, %Y' }}

produces more reader friendly dates like:

November 29, 2013

Much better, but depending on the date, subtle design issues show up. For example, during the first nine days of each month "leading zeros" crop up (e.g. "August 03, 2013" instead of "August 3, 2013"). Other gotchas with the basic Liquid filters include:

Adding a period behind the abbreviated month names has to be adjusted to handle May. For example, "Aug. 16, 2013" is fine. "May. 16, 2013" is not.

September is generally abbreviated "Sept." instead of Liquid's default "Sep."

To comply with the AP style guide the months April, May, June and July should not be abbreviated. Similar alterations are necessary to meet with the guidelines from the Chicago Manual of Style.

Most designs go with the available defaults. Either using a format that doesn't have these issues or, more frequently, letting the details slip. The information still gets across and every web site has a punch list of potential modifications that stretches to the horizon. So, I understand putting off finding a solution, but not having proper date formatting has always bugged me. While solving the issue for myself5, I decided to put together this post as a public reference as well. I don't yet have the Ruby chops to contribute directly to Jekyll, but I can provide this reference to give back a little at least.

This set of Liquid date filters solves the issues listed above and explores a few other formatting options. Each one provides a solution for a specific display format and is provided with four output examples for the following date: 1) May 3, 2013, 2) July 4, 2013, 3) September 23, 2013 and 4) November 26, 2013. These examples demonstrate if/how the various formatting issues are handled. After the examples, a few snippets of code for individual elements are provided. With these samples, just about any date format desired should be within easy reach.

These individual snippets are for a few of the tricker formatting filters. Some that weren't used in the examples above. For those interested in the approach, the hack I'm using to remove leading zeros is to add "0" to the string. This turns the string into an integer. When the integer is rendered back as a string the leading zero disappears. Hurray for dynamic typing.

With that, you should be in pretty good shape. If you can't directly create what you need from the above samples or snippets you should at least be able to use a similar approach to piece together what you need.

Notes on the Examples

The hour, minute and second parts of the full date/time stamp aren't being used because Jekyll tends to zero them out.

In some of the examples, the code is split to multiple lines to help readability. If it's a natural break point where white space already exists, this won't effect HTML rendering. In some cases, it will introduce unwanted white space. Simply move everything back to one line to create the desired presentation.

Since the original version of this post went up, updates have been made to use the cleaner version of {{ page.date | date: "%-m" }} instead of {{ page.date | date: "%m" | plus:'0' }} and {{ page.date | date: "%-d" }} instead of {{ page.date | date: "%d" | plus:'0' }} to remove leading zeros.

An additional update was made to add an example for non-English month names.

Observant readers will notice that as of the time this post went live, my design still uses a date format with leading zeros. I have the solution, it just hasn't been implement yet. It'll go in with the next set of design changes.

ISO 8601 - "Data elements and interchange formats - Information interchange - Representation of dates and times is an international standard covering the exchange of date and time-related data." A perfect example of how Time really is wibbly wobbly timey wimey… stuff.