Formatting Dates and Times in Liquid:

Liquid time and date filters

Summary

Learn how to format dates and times in Liquid using filters like date and time_tag, covering machine-readable formats (ISO 8601), localization, timezone handling, and Schema.org best practices. The article includes practical examples for blogs, events, and structured data.

Published:

2025-06-07

Updated:

2025-06-07

Reading time:

04:56

Author:

Jonas Jared Jacek

Tags:

liquid, web development

License:

CC BY-SA 4.0

Permalink:

Liquid time and date filters

Introduction #

Timestamps are structured representations of dates and times, commonly used to store and display temporal data. In Liquid, timestamps are formatted using built-in filters such as date, time_tag, and the datetime parameter.

The Liquid date filter #

The date filter is used to format a timestamp or string into a human-readable date or time. It accepts a formatting string using Ruby’s strftime syntax.

Date format specifiers #

Here are some commonly used format specifiers:

The Liquid time_tag filter #

The time_tag filter outputs a complete HTML <time> element. It can display both human-readable and machine-readable time.

Time format specifiers #

The format specifiers used in time_tag follow the same pattern as in the date filter. The key difference is that time_tag generates HTML output.

Example:

{{ article.published_at | time_tag }}

Output:

<time datetime="2025-06-07T14:55:00+02:00">Sat, Jun 7, 2025, 2:55 pm CEST</time>

The time_tag filter may not be present in all Liquid implementations.

The Liquid datetime parameter #

The datetime parameter is used with the time_tag filter to specify the machine-readable value of the <time> element. It is often formatted using the ISO 8601 standard.

Example:

{{ article.published_at | time_tag: '%B %d, %Y', datetime: article.published_at | date: '%Y-%m-%d' }}

Output:

<time datetime="2025-06-07">Sat, Jun 7, 2025</time>

The datetime parameter may not be present in all Liquid implementations.

Using Liquid time and date filters #

You can use Liquid filters to output time in HTML elements and structured data formats such as JSON-LD.

HTML <time> element #

The HTML <time> element represents a specific date, time, or both in a machine-readable way. It supports the datetime attribute, which holds a string in the ISO 8601 format. This element helps browsers, search engines, and assistive technologies to interpret dates and times correctly.

Example 1 #

This example shows how to output the date of a page in a readable format while keeping a machine-readable ISO 8601 value in the datetime attribute.

<time datetime="{{ page.date | date: '%Y-%m-%d' }}">
  {{ page.date | date: '%B %d, %Y' }}
</time>

The HTML timestamps will look like this:

<time datetime="2025-06-07">
  June 07, 2025
</time>

Example 2 #

This example uses the time_tag filter with both a display format and a datetime attribute for SEO and semantic value.

{{ page.date | time_tag: '%b %e, %Y', datetime: page.date | date: '%Y-%m-%d' }}

The HTML timestamps will look like this:

<time datetime="2025-06-07">Jun  7, 2025</time>

Example 3 #

This example includes both the full date and time with timezone offset, using site.time to show when the site was built or published.

<time datetime="{{ site.time | date: '%Y-%m-%dT%H:%M:%S%:z' }}">
  {{ site.time | date: '%A, %B %d, %Y at %I:%M %p' }}
</time>

The HTML timestamps will look like this:

<time datetime="2025-06-07T14:35:00+00:00">
  Saturday, June 07, 2025 at 02:35 PM
</time>

Date Schema #

Schema.org markup includes fields like datePublished, dateModified, and startDate. These should follow the ISO 8601 format (YYYY-MM-DD) and can be generated using the date filter in Liquid.

Example 1 #

Outputs the publication date of a page in a machine-readable format.

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

The timestamp will look like this:

"datePublished": "2025-06-07"

Example 2 #

Outputs the last modified date for a page in ISO 8601 format.

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

The timestamp will look like this:

"dateModified": "2025-06-05"

Example 3 #

Shows the start date of an event in the correct schema.org date format.

"startDate": "{{ event.start_time | date: '%Y-%m-%d' }}"

The timestamp will look like this:

"startDate": "2025-08-15"

Time Schema #

When using Schema.org for events, times must be expressed using the full time format (HH:MM:SS) compliant with ISO 8601. Use the date filter to output time-only values.

Example 1 #

Outputs the event’s start time in ISO format.

"startTime": "{{ event.start_time | date: '%Y-%m-%dT%H:%M:%S' }}"

The timestamp will look like this:

"startTime": "2025-08-15T18:30:00"

Example 2 #

Outputs the event’s end time using the full date and time with seconds.

"endTime": "{{ event.end_time | date: '%Y-%m-%dT%H:%M:%S' }}"

The timestamp will look like this:

"endTime": "2025-08-15T21:00:00"

Example 3 #

Outputs the door opening time for the event using the full timestamp.

"doorTime": "{{ event.door_time | date: '%Y-%m-%dT%H:%M:%S' }}"

The timestamp will look like this:

"doorTime": "2025-08-15T18:00:00"

Schema.org Best Practices #

Always include timezone offsets (%:z) in Schema.org markup for ISO 8601 compliance:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Event",
  "startDate": "{{ event.start_time | date: '%Y-%m-%dT%H:%M:%S%:z' }}"
}
</script>

Key Difference:

• %z → +0200 (no colon)
• %:z → +02:00 (Schema.org compliant)

Common Use Cases #

Timezone Handling #

Liquid doesn’t natively handle timezone conversions, but you can output timezone-aware timestamps using format specifiers:

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

For dynamic timezone conversion, use JavaScript or backend logic (e.g., Shopify’s `in_time_zone` filter or Jekyll plugins).

Relative Time #

For “time ago” formats (e.g., “2 days ago”), use platform-specific filters or plugins:

{{ page.date | time_ago }}

• Jekyll: Requires plugins like jekyll-time-ago.
• Shopify: Uses distance_of_time_in_words.

Relative time filters may not be available in all Liquid implementations.

Localization (Multi-Language Support) #

Localize dates by replacing English terms or using translation files:

{{ page.date | date: "%A, %d %B %Y" | replace: "Monday", "Lundi" }}

Workarounds:

• Use replace for small-scale translations.
• Store translations in a _data file (Jekyll) or Shopify metafields.

Blog Post Dates #

<span class="post-meta">
  Posted on <time datetime="{{ page.date | date: '%Y-%m-%d' }}">
    {{ page.date | date: "%b %e, %Y" }}
  </time>
</span>

Countdowns (Future Dates) #

{% assign event_date = "2025-12-31" | date: "%s" %}
{% assign now = "now" | date: "%s" %}
{% assign diff = event_date | minus: now %}

Opening Hours (Schema-Ready) #

"openingHours": "Mo-Fr {{ business.opening_time | date: "%H:%M" }}-{{ business.closing_time | date: "%H:%M" }}"

Edge Cases & Troubleshooting #

Invalid Dates #

Handle empty/null values with default:

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

Unix Timestamps #

Convert Unix timestamps to readable dates:

{{ 1717747200 | date: "%Y-%m-%d" }}

All time and date format specifiers in Liquid #

Reference table of all time and date format specifiers in Liquid:

Further readings #

Sources and recommended, further resources on the topic:

• Shopify: Liquid date filter documentation
• Jekyll: Liquid Filters
• MDN Web Docs: HTML <time> element
• Schema.org: Date
• Schema.org: Time
• Ruby Lang: Formats for Dates and Times
• Date and Time on the Internet: Internet timestamps

Author

Jonas Jared Jacek (J15k)

Jonas works as project manager, web designer, and web developer since 2001. On top of that, he is a Linux system administrator with a broad interest in things related to programming, architecture, and design. See: https://www.j15k.com/

<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://www.ditig.com/liquid-time-and-date-filters">Liquid time and date filters</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://www.j15k.com/">Jonas Jared Jacek</a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="license noopener noreferrer">CC BY-SA 4.0</a>.</p>