Jekyll-Timeago

A Ruby library to compute distance of dates in words, with localization support. Originally built for Jekyll.

Main features:

• Compute distance of dates, in words: 1 week and 2 days ago, 5 months ago
• Future times: in 1 year
• Alternative formats: short (2y and 1mo ago), array (['2 years', '1 month']), and hash ({years: 2, months: 1})
• Out of the box support for Jekyll projects, available as a Liquid Filter and as a Liquid Tag
• Localization: hace 3 semanas, 3週間前, il y a environ 3 semaines
• Level of detail customization
• CLI
• Approximate distance, with customizable threshold: 366 days becomes 1 year ago instead of 1 year and 1 day ago

In fact, jekyll-timeago started as an extension for the Liquid template engine, to be used in Jekyll backed sites. But actually, you can use it easily on any Ruby project and even as a tool from the terminal!

Read more about the Jekyll integration in this section.

Installation

Add this line to your application's Gemfile:

gem 'jekyll-timeago'

And then execute:

> bundle install

Or install it yourself as:

> gem install jekyll-timeago

Usage

The gem provides the timeago method:

Jekyll::Timeago.timeago(from, to = Date.today, options = {})

You can include the method in the current context by including the module (so you can call directly the timeago method without using the whole scope):

include Jekyll::Timeago

Examples:

>> timeago(Date.today)
=> "today"
>> timeago(Date.today.prev_day)
=> "yesterday"
>> timeago(Date.today.prev_day(10))
=> "1 week and 3 days ago"
>> timeago(Date.today.prev_day(100))
=> "3 months and 1 week ago"
>> timeago(Date.today.prev_day(500))
=> "1 year and 4 months ago"
>> timeago('2010-1-1', '2012-1-1')
=> "2 years ago"
>> timeago(Date.today.next_day)
=> "tomorrow"
>> timeago(Date.today.next_day(7))
=> "in 1 week"
>> timeago(Date.today.next_day(1000))
=> "in 2 years and 8 months"

NOTE If you have the gem installed in your system globally, and you're not using Bundler (probably because you're are writing a small script), don't forget to require the library first:

require 'jekyll-timeago'
include Jekyll::Timeago

puts timeago('2030-1-1')

Options

locale

To use a different language:

>> timeago(Date.today.prev_day(200), locale: :es)
=> "hace 6 meses y 2 semanas"
>> timeago(Date.today.prev_day(200), locale: :fr)
=> "il y a environ 6 mois et 2 semaines"

Read more about the localization options here.

depth

You are able to change the level of detail (from 1 up to 4, 2 by default) to get higher or lower granularity:

>> timeago(Date.today.prev_day(2000), depth: 3)
=> "5 years, 5 months and 3 weeks ago"
>> timeago(Date.today.prev_day(2000), depth: 4)
=> "5 years, 5 months, 3 weeks and 4 days ago"

threshold

The next component in the time must at least match this threshold to be picked. Set to 0 by default, so you don't get any approximations. Can be used to drop "straggling" values which are too low to be of any use (in 7 months and 2 days is as good as saying in 7 months).

>> timeago(Date.today.prev_day(366), depth: 2, threshold: 0.05)
=> "1 year ago"

style

Use :short style for abbreviated time formats:

>> timeago(Date.today.prev_day(365), style: :short)
=> "1y ago"
>> timeago(Date.today.prev_day(30), style: :short)
=> "1mo ago"
>> timeago(Date.today.prev_day(7), style: :short)
=> "1w ago"

Use :array style for structured data:

>> timeago(Date.today.prev_day(365), style: :array)
=> ["1 year"]
>> timeago(Date.today.prev_day(160), style: :array)
=> ["5 months", "1 week"]
>> timeago(Date.today.prev_day(160), style: :array, locale: :es)
=> ["5 meses", "1 semana"]

Use :hash style for structured hash data:

>> timeago(Date.today.prev_day(365), style: :hash)
=> {:years=>1}
>> timeago(Date.today.prev_day(160), style: :hash)
=> {:months=>5, :weeks=>1}
>> timeago(Date.today.prev_day(160), style: :hash, locale: :es)
=> {:meses=>5, :semanas=>1}

only

Use the only option to accumulate all time into a single unit. Supported values are :years, :months, :weeks, and :days:

>> timeago(Date.today.prev_day(365), only: :weeks)
=> "52 weeks ago"
>> timeago(Date.today.prev_day(365), only: :months)
=> "12 months ago"
>> timeago(Date.today.prev_day(100), only: :weeks)
=> "14 weeks ago"
>> timeago(Date.today.prev_day(500), only: :days)
=> "500 days ago"
>> timeago(Date.today.prev_day(365), only: :weeks, style: :short)
=> "52w ago"
>> timeago(Date.today.prev_day(365), only: :months, locale: :es)
=> "hace 12 meses"
>> timeago(Date.today.prev_day(365), only: :months, style: :hash)
=> {:months=>12}

Localization

By default, jekyll-timego already provides translations for some languages. You can check the list here. However, you are able to provide your own translations, or even override the originals, easily.

This project uses the mini_i18n gem under the hood to deal with translations. You can read further about all options in its docs. Example:

MiniI18n.configure do |config|
  config.load_translations('/path_to_your_translations_files/*.yml')
  config.default_locale = :es
end

If you want to contribute and support more default languages, please feel free to send a pull request.

CLI

You can also use jekyll-timeago from the command line:

> timeago --help
> timeago 2016-1-1
2 years and 6 months ago
> timeago 2016-1-1 --locale fr
il y a environ 2 années et 6 mois
> timeago 2016-1-1 2018-1-1 --style short
2y ago
> timeago 2016-1-1 2018-1-1 -l es -s short
hace 2a y 1d
> timeago 2016-1-1 2018-1-1 --style hash
{:years=>2, :days=>1}
> timeago 2016-1-1 2018-1-1 --only weeks
104 weeks ago
> timeago 2016-1-1 2018-1-1 --only months -s short
24mo ago

Console

Starts a custom IRB session with the timeago method included:

> timeago --console
>> timeago(Date.today)
=> "today"

Jekyll integration

You have different options to install and use jekyll-timeago into your Jekyll project:

• Via Jekyll plugin system

Install the gem to your system:

> gem install jekyll-timeago

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:

plugins:
  - jekyll-timeago

• Via Bundler

Add this gem to your Gemfile and run bundle install:

group :jekyll_plugins do
  gem 'jekyll-timeago'
end

Usage

Liquid Filter:

<p>{{ page.date | timeago }}</p>
<p>{{ page.date | timeago: '2020-1-1' }}</p>

Liquid Tag:

<p>{% timeago 2000-1-1 %}</p>
<p>{% timeago 2000-1-1 2010-1-1 %}</p>

Configuration

In your _config.yml file, you can customize the following options:

jekyll_timeago:
  depth: 2
  translations_path: '/path_to_your_translations/*.yaml'
  default_locale: 'en'
  fallbacks: true
  available_locales:
    - 'en'
    - 'es'
    - 'fr'

Also, you can set a different language per page using the Front Matter functionality:

---
locale: 'es'
---

Development

Any kind of feedback, bug report, idea or enhancement are really appreciated.

To contribute, just fork the repo, hack on it and send a pull request. Don't forget to add specs for behaviour changes and run the test suite:

> bundle exec rspec

License

Copyright (c) Marc Anguera. Jekyll-Timeago is released under the MIT License.