Jekyll One

Jekyll User Guide

Date formats for Jekyll

These examples provide tested code snippets for displaying several date formats on a Jekyll site. They should also work on GitHub Pages, Shopify or anything else that uses Liquid.

Overview

Jekyll (the simple, blog aware, static website generator) uses Shopify’s Liquid Template Engine3. Displaying dates is done using the “2022-01-01 00:00:00 +0000” supplied Liquid tag4. With no other alteration, the dates produced look something like:

2013-11-29 00:00:00 -0500

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:

January 01, 2022

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:

  1. 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.

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

  3. 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.

Built-in Jekyll Date Filters

Date to String

{{ page.date | date_to_string }}

Output Example

01 Jan 2022

Date to Long String

{{ page.date | date_to_long_string }}

Output Example

01 January 2022

Date to XML Schema

{{ page.date | date_to_xmlschema }}

Output Example

2022-01-01T01:00:00+01:00

Date to RFC-822

{{ page.date | date_to_rfc822 }}

Output Example

Sat, 01 Jan 2022 01:00:00 +0100

Liquid Date Formatting

Liquid Jekyll Date Formatting Examples.

ISO 8601 Date

{{ page.date | date: "%Y-%m-%d" }}

Output Example

2022-01-01

U.S. Numeric Style with Four Digit Years

{{ page.date | date: "%m/%d/%Y" }}

Output Example

01/01/2022

U.S. Numeric Style with Four Digit Years

{{ page.date | date: "%-m/%-d/%Y" }}

Output Example

1/1/2022

U.S. Numeric Style with Two Digit Year

{{ page.date | date: "%-m/%-d/%y" }}

Output Example

1/1/22

Outside U.S. Style with Full Month Name

{{ page.date | date: "%-d %B %Y" }}

Output Example

1 January 2022

Non-English Full Month Name

This example uses the German names for months. Any other language can be used by simply substituting the proper names for each month.


<!-- Whitespace added for readability -->
{% assign m = page.date | date: "%-m" %}
{{ page.date | date: "%-d" }}
{% case m %}
  {% when '1' %}Januar
  {% when '2' %}Februar
  {% when '3' %}M&auml;rz
  {% when '4' %}April
  {% when '5' %}Mai
  {% when '6' %}Juni
  {% when '7' %}Juli
  {% when '8' %}August
  {% when '9' %}September
  {% when '10' %}Oktober
  {% when '11' %}November
  {% when '12' %}Dezember
{% endcase %}
{{ page.date | date: "%Y" }}

Output Example

1
Januar
2022

U.S. Style with Full Month Name

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

  1. Output Example: May 3, 2013

  2. Output Example: July 4, 2013

  3. Output Example: September 23, 2013

  4. Output Example: November 26, 2013

U.S. Style with Full Month Names and Ordinalized Days


<!-- Whitespace added for readability -->
{% assign d = page.date | date: "%-d"  %}
{{ page.date | date: "%B" }}
{% case d %}
  {% when '1' or '21' or '31' %}{{ d }}st
  {% when '2' or '22' %}{{ d }}nd
  {% when '3' or '23' %}{{ d }}rd
  {% else %}{{ d }}th
  {% endcase %},
{{ page.date | date: "%Y" }}

  1. Output Example: May 3rd, 2013

  2. Output Example: July 4th, 2013

  3. Output Example: September 23rd, 2013

  4. Output Example: November 26th, 2013

U.S. Style with AP Month Abbreviations and Ordinalized Days


<!-- Whitespace added for readability -->
{% assign d = page.date | date: "%-d" %}
{% assign m = page.date | date: "%B" %}

{% case m %}
  {% when 'April' or 'May' or 'June' or 'July' %}{{ m }}
  {% when 'September' %}Sept.
  {% else %}{{ page.date | date: "%b" }}.
  {% endcase %}
{% case d %}
  {% when '1' or '21' or '31' %}{{ d }}st
  {% when '2' or '22' %}{{ d }}nd
  {% when '3' or '23' %}{{ d }}rd
  {% else %}{{ d }}th
  {% endcase %},
{{ page.date | date: "%Y" }}

  1. Output Example: May 3rd, 2013

  2. Output Example: July 4th, 2013

  3. Output Example: Sept. 23rd, 2013

  4. Output Example: Nov. 26th, 2013

U.S. Style Full Day and Full Month Names

{{ page.date | date: "%A, %B %-d, %Y" }}

  1. Output Example: Friday, May 3, 2013

  2. Output Example: Thursday, July 4, 2013

  3. Output Example: Monday, September 23, 2013

  4. Output Example: Tuesday, November 26, 2013

Chicago Manual of Style Day Abbreviations and U.S. Style Date


<!-- Whitespace added for readability -->
{% assign dy = page.date | date: "%a" %}
{% case dy %}
  {% when "Tue" %}Tues
  {% when "Thu" %}Thurs
  {% else %}{{ dy }}
  {% endcase %}

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

Snippets for Liquid Date Formatting

Output Example: Tues. ~ November 26, 2013

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.

Numeric Month with Leading Zeros Removed

{{ page.date | date: "%-m" }}

Output Example

1

Numeric Day with Leading Zeros Removed

{{ page.date | date: "%-d" }}

Output Example

1

Ordinalized Numeric Day with Leading Zeros Removed


{% assign d = page.date | date: "%-d" %}
{% case d %}
  {% when '1' or '21' or '31' %}{{ d }}st
  {% when '2' or '22' %}{{ d }}nd
  {% when '3' or '23' %}{{ d }}rd
  {% else %}{{ d }}th
  {% endcase %}

Output Example

1st

AP Style Month Abbreviations


{% assign m = page.date | date: "%B" %}
{% case m %}
  {% when 'April' or 'May' or 'June' or 'July' %}{{ m }}
  {% when 'September' %}Sept.
  {% else %}{{ page.date | date: "%b" }}.
{% endcase %}

Produces: "Jan.", "Feb.", "Mar.", "April", "May", "June", "July", "Aug.", "Sept.", "Oct.", "Nov.", "Dec."

Output Example

Jan.

Chicago Manual of Style Day Abbreviations


{% assign dy = page.date | date: "%a" %}
{% case dy %}
  {% when "Tue" %}Tues
  {% when "Thu" %}Thurs
  {% else %}{{ dy }}
  {% endcase %}

Produces: "Sun.", "Mon.", "Tues.", "Wed.", "Thurs.", "Fri.", "Sat."

Chicago Manual of Style Month Abbreviations


{% assign m = page.date | date: "%B" %}
{% case m %}
  {% when 'May' or June' or 'July' %}{{ m }}
  {% when 'September' %}Sept.
  {% else %}{{ page.date | date: "%b" }}.
  {% endcase %}

Produces: "Jan.", "Feb.", "Mar.", "Apr.", "May", "June", "July", "Aug.", "Sept.", "Oct.", "Nov.", "Dec."

Non-English Month Names


{% assign m = page.date | date: "%-m" %}
{% case m %}
  {% when '1' %}Januar
  {% when '2' %}Februar
  {% when '3' %}M&auml;rz
  {% when '4' %}April
  {% when '5' %}Mai
  {% when '6' %}Juni
  {% when '7' %}Juli
  {% when '8' %}August
  {% when '9' %}September
  {% when '10' %}Oktober
  {% when '11' %}November
  {% when '12' %}Dezember
{% endcase %}

Produces: "Januar", "Febuar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"

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.

Format directives

ISO 8601 formats

Table 1. All ISO 8601 formats available for date
Format Description Example

%Y%m%d

Calendar date (basic)

19540918

%F

Calendar date (extended)

1980-08-26

%Y-%m

Calendar date, reduced accuracy, specific month

19560627

%Y

Calendar date, reduced accuracy, specific year

19581025

%C

Calendar date, reduced accuracy, specific century

19

%Y%j

Ordinal date (basic)

1980363

%Y-%j

Ordinal date (extended)

2004-217

%GW%V%u

Week date (basic)

1978W362

%G-W%V-%u

Week date (extended)

1973-W32-7

%GW%V

Week date, reduced accuracy, specific week (basic)

1978W29

%G-W%V

Week date, reduced accuracy, specific week (extended)

1997-W51

%G-W%V-%u

Week date (extended)

2005-W51-2

%H%M%S

Local time (basic)

083748

%T

Local time (extended)

08:37:48

%H%M

Local time, reduced accuracy, specific minute (basic)

0837

%H:%M

Local time, reduced accuracy, specific minute (extended)

08:37

%H

Local time, reduced accuracy, specific hour

08

%H%M%S,%L

Local time with decimal fraction, comma as decimal sign (basic)

083748,000

%T,%L

Local time with decimal fraction, comma as decimal sign (extended)

08:37:48,000

%H%M%S.%L

Local time with decimal fraction, full stop as decimal sign (basic)

083748.000

%T.%L

Local time with decimal fraction, full stop as decimal sign (extended)

08:37:48.000

%H%M%S%z

Local time and the difference from UTC (basic)

083748-0600

%T%:z

Local time and the difference from UTC (extended)

08:37:48+01:00

%Y%m%dT%H%M%S%z

Date and time of day for calendar date (basic)

20071119T083748-0600

%FT%T%:z

Date and time of day for calendar date (extended)

2007-11-19T08:37:48+01:00

%Y%jT%H%M%S%z

Date and time of day for ordinal date (basic)

2007323T083748-0600

%Y-%jT%T%:z

Date and time of day for ordinal date (extended)

2007-323T08:37:48+01:00

%GW%V%uT%H%M%S%z

Local time, reduced accuracy, specific hour

Date and time of day for week date (basic)

%G-W%V-%uT%T%:z

Date and time of day for week date (extended)

2007-W47-1T08:37:48+01:00

%Y%m%dT%H%M

Calendar date and local time (basic)

20071119T0837

`%FT%R `

Calendar date and local time (extended)

2007-11-19T08:37

%Y%jT%H%MZ

Ordinal date and UTC of day (basic)

2007323T0837Z

%Y-%jT%RZ

Ordinal date and UTC of day (extended)

2007-323T08:37Z

%GW%V%uT%H%M%z

Week date and local time and difference from UTC (basic)

2007W471T0837-0600

%G-W%V-%uT%R%:z

Week date and local time and difference from UTC (extended)

2007-W47-1T08:37+01:00

Date (Year, Month, Day)

Table 2. Year, Month, Day shortcuts of ISO 8601
Format Description Example

%Y

Year with century if provided, will pad result at least 4 digits

-0001, 0000, 1995, 2009, 14292

%C

Year / 100 (rounded down such as 20 in 2009)

20

%y

Year % 100 (00..99)

75

%m

Month of the year, zero-padded (01..12)

  • %_m blank-padded ( 1..12)

  • %-m no-padded (1..12)

5 | 10

%B

The full month name (``January'')

  • %^B uppercased (``JANUARY'')

May | DECEMBER

%b

The abbreviated month name (Jan'') * %^b uppercased (JAN'')

May | OCT

%h

%h - Equivalent to %b

Sep

%d

Day of the month, zero-padded (01..31) * %-d no-padded (1..31)

02 | -02

%e

Day of the month, blank-padded ( 1..31)

22

%j

Day of the year (001..366)

159

Time (Hour, Minute, Second, Subsecond)

  %H - Hour of the day, 24-hour clock, zero-padded (00..23)
  %k - Hour of the day, 24-hour clock, blank-padded ( 0..23)
  %I - Hour of the day, 12-hour clock, zero-padded (01..12)
  %l - Hour of the day, 12-hour clock, blank-padded ( 1..12)
  %P - Meridian indicator, lowercase (``am'' or ``pm'')
  %p - Meridian indicator, uppercase (``AM'' or ``PM'')
  %M - Minute of the hour (00..59)
  %S - Second of the minute (00..60)
  %L - Millisecond of the second (000..999)
       The digits under millisecond are truncated to not produce 1000.
  %N - Fractional seconds digits, default is 9 digits (nanosecond)
        %3N  millisecond (3 digits)
        %6N  microsecond (6 digits)
        %9N  nanosecond (9 digits)
        %12N picosecond (12 digits)
        %15N femtosecond (15 digits)
        %18N attosecond (18 digits)
        %21N zeptosecond (21 digits)
        %24N yoctosecond (24 digits)
        The digits under the specified length are truncated to avoid
        carry up.

Time zone

  %z - Time zone as hour and minute offset from UTC (e.g. +0900)
  %:z - hour and minute offset from UTC with a colon (e.g. +09:00)
  %::z - hour, minute and second offset from UTC (e.g. +09:00:00)
  %Z - Abbreviated time zone name or similar information.  (OS dependent)

Weekday

  %A - The full weekday name (``Sunday'')
          %^A  uppercased (``SUNDAY'')
  %a - The abbreviated name (``Sun'')
          %^a  uppercased (``SUN'')
  %u - Day of the week (Monday is 1, 1..7)
  %w - Day of the week (Sunday is 0, 0..6)

ISO 8601 week-based year and week number

The first week of YYYY starts with a Monday and includes YYYY-01-04. The days in the year before the first week are in the last week of the previous year.

  %G - The week-based year
  %g - The last 2 digits of the week-based year (00..99)
  %V - Week number of the week-based year (01..53)

Week number

The first week of YYYY that starts with a Sunday or Monday (according to %U or %W). The days in the year before the first week are in week 0.

  %U - Week number of the year. The week starts with Sunday. (00..53)
  %W - Week number of the year. The week starts with Monday. (00..53)

Seconds since the Epoch

  %s - Number of seconds since 1970-01-01 00:00:00 UTC.

Literal strings

  %n - Newline character (\n)
  %t - Tab character (\t)
  %% - Literal ``%'' character

Combinations

  %c - date and time (%a %b %e %T %Y)
  %D - Date (%m/%d/%y)
  %F - The ISO 8601 date format (%Y-%m-%d)
  %v - VMS date (%e-%^b-%4Y)
  %x - Same as %D
  %X - Same as %T
  %r - 12-hour time (%I:%M:%S %p)
  %R - 24-hour time (%H:%M)
  %T - 24-hour time (%H:%M:%S)