Jul 2013

Jekyll-Timeago: Time ago date filter for Jekyll

Custom and simple implementation of timeago date filter. Main features:

  • Localization
  • Future time
  • Level of detail

In fact, jekyll-timeago is an extension of Liquid filters, so you can use it in all your Liquid templates (Octopress as well). Liquid is markup language extracted from the e-commerce platform Shopify.

Source code, bug tracking and updates here.


You have 3 options for installing the plugin:

Via Jekyll plugin system

In your _config.yml file, add a new array with the key gems and the values of the gem names of the plugins you’d like to use. In this case:

gems: [jekyll-timeago]

Via Bundler

Add this gem to your Gemfile and run bundle:

gem 'jekyll-timeago'

To use this filter, just add the following to the top of another plugin (found under _plugins/):

require 'jekyll/timeago'


Alternatively, you can simply copy this file directly into your _plugins/ directory! :)


Example usage:

<span>{{ | timeago }}</span>
<h2>{{ page.title }}</h2>

<div class="post">
  {{ content }}

You are able to personalize the level of detail (from 1 up to 4, 2 by default) by passing a parameter:

<span>{{ | timeago: 4 }}</span>


The plugin allows you to modify the strings needed to build the time ago sentences. For do this, you must add some extra keys to your _config.yml. You can simply copy them from this example file and translate it to your site’s language. Sample:

  today: 'today'
  yesterday: 'yesterday'
  tomorrow: 'tomorrow'
  and: 'and'
  suffix: 'ago'
  prefix: ''
  suffix_future: 'in'
  prefix_future: ''
  years: 'years'
  year: 'year'
  months: 'months'
  month: 'month'
  weeks: 'weeks'
  week: 'week'
  days: 'days'
  day: 'day'

Output Examples

Default behavior:

> timeago(
=> "today"
> timeago( -
=> "yesterday"
> timeago( - 10.days)
=> "1 week and 3 days ago"
> timeago( - 100.days)
=> "3 months and 1 week ago"
> timeago( - 500.days)
=> "1 year and 4 months ago"
> timeago( + 1.days)
=> "tomorrow"
> timeago( + 7.days)
=> "in 1 week"
> timeago( + 1000.days)
=> "in 2 years and 8 months"

You can modify the level of detail to get higher or lower granularity:

> timeago( - 500.days) # default
=> "1 year and 4 months ago"
> timeago( - 500.days, 3)
=> "1 year, 4 months and 1 week ago"
> timeago( - 500.days, 4)
=> "1 year, 4 months, 1 week and 4 days ago"
> timeago( - 500.days, 1)
=> "1 year ago"


Any kind of idea, bug or comment are welcome. Please, follow up in GitHub.