{"id":13612190,"url":"https://github.com/markets/jekyll-timeago","last_synced_at":"2025-10-24T12:38:09.460Z","repository":{"id":8891440,"uuid":"10611254","full_name":"markets/jekyll-timeago","owner":"markets","description":"⌛ Ruby library to compute distance of dates in words. Originally built for Jekyll.","archived":false,"fork":false,"pushed_at":"2023-07-25T09:21:08.000Z","size":124,"stargazers_count":147,"open_issues_count":2,"forks_count":24,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-28T18:08:53.112Z","etag":null,"topics":["cli-utilities","jekyll","jekyll-plugin","liquid","relative-time","ruby","timeago"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markets.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-06-10T23:01:01.000Z","updated_at":"2024-12-06T00:59:28.000Z","dependencies_parsed_at":"2024-06-18T18:24:57.569Z","dependency_job_id":"62ef1f9d-f0c5-4bdb-9e50-de89da04b76a","html_url":"https://github.com/markets/jekyll-timeago","commit_stats":{"total_commits":138,"total_committers":11,"mean_commits":"12.545454545454545","dds":0.09420289855072461,"last_synced_commit":"18649e5d8814a22683bb8ad2e5c099d2899210ac"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markets%2Fjekyll-timeago","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markets%2Fjekyll-timeago/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markets%2Fjekyll-timeago/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markets%2Fjekyll-timeago/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markets","download_url":"https://codeload.github.com/markets/jekyll-timeago/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234921,"owners_count":20905854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli-utilities","jekyll","jekyll-plugin","liquid","relative-time","ruby","timeago"],"created_at":"2024-08-01T20:00:24.381Z","updated_at":"2025-10-24T12:38:09.455Z","avatar_url":"https://github.com/markets.png","language":"Ruby","funding_links":[],"categories":["Text Filters","Ruby","Date and Time Processing"],"sub_categories":[],"readme":"# Jekyll-Timeago\n\n[![Gem Version](https://img.shields.io/gem/v/jekyll-timeago.svg)](https://rubygems.org/gems/jekyll-timeago)\n[![Build Status](https://github.com/markets/jekyll-timeago/workflows/CI/badge.svg)](https://github.com/markets/jekyll-timeago/actions)\n[![Maintainability](https://api.codeclimate.com/v1/badges/a8be458ba0532c2d057d/maintainability)](https://codeclimate.com/github/markets/jekyll-timeago/maintainability)\n\n\u003e A Ruby library to compute distance of dates in words, with localization support. Originally built for Jekyll.\n\nMain features:\n\n- Compute distance of dates, in words: `1 week and 2 days ago`, `5 months ago`\n- Future times: `in 1 year`\n- Alternative formats: short (`2y and 1mo ago`), array (`['2 years', '1 month']`), and hash (`{years: 2, months: 1}`)\n- Out of the box support for `Jekyll` projects, available as a Liquid Filter and as a Liquid Tag\n- Localization: `hace 3 semanas`, `3週間前`, `il y a environ 3 semaines`\n- Level of detail customization\n- CLI\n- Approximate distance, with customizable threshold: `366 days` becomes `1 year ago` instead of `1 year and 1 day ago`\n\nIn fact, `jekyll-timeago` started as an extension for the [Liquid](https://github.com/Shopify/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](#cli)!\n\nRead more about the `Jekyll` integration [in this section](#jekyll-integration).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'jekyll-timeago'\n```\n\nAnd then execute:\n\n    \u003e bundle install\n\nOr install it yourself as:\n\n    \u003e gem install jekyll-timeago\n\n## Usage\n\nThe gem provides the `timeago` method:\n\n```ruby\nJekyll::Timeago.timeago(from, to = Date.today, options = {})\n```\n\nYou 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):\n\n```ruby\ninclude Jekyll::Timeago\n```\n\nExamples:\n\n```ruby\n\u003e\u003e timeago(Date.today)\n=\u003e \"today\"\n\u003e\u003e timeago(Date.today.prev_day)\n=\u003e \"yesterday\"\n\u003e\u003e timeago(Date.today.prev_day(10))\n=\u003e \"1 week and 3 days ago\"\n\u003e\u003e timeago(Date.today.prev_day(100))\n=\u003e \"3 months and 1 week ago\"\n\u003e\u003e timeago(Date.today.prev_day(500))\n=\u003e \"1 year and 4 months ago\"\n\u003e\u003e timeago('2010-1-1', '2012-1-1')\n=\u003e \"2 years ago\"\n\u003e\u003e timeago(Date.today.next_day)\n=\u003e \"tomorrow\"\n\u003e\u003e timeago(Date.today.next_day(7))\n=\u003e \"in 1 week\"\n\u003e\u003e timeago(Date.today.next_day(1000))\n=\u003e \"in 2 years and 8 months\"\n```\n\n**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:\n\n```ruby\nrequire 'jekyll-timeago'\ninclude Jekyll::Timeago\n\nputs timeago('2030-1-1')\n```\n\n### Options\n\n#### `locale`\n\nTo use a different language:\n\n```ruby\n\u003e\u003e timeago(Date.today.prev_day(200), locale: :es)\n=\u003e \"hace 6 meses y 2 semanas\"\n\u003e\u003e timeago(Date.today.prev_day(200), locale: :fr)\n=\u003e \"il y a environ 6 mois et 2 semaines\"\n```\n\nRead more about the localization options [here](#localization).\n\n#### `depth`\n\nYou are able to change the level of detail (from 1 up to 4, 2 by default) to get higher or lower granularity:\n\n```ruby\n\u003e\u003e timeago(Date.today.prev_day(2000), depth: 3)\n=\u003e \"5 years, 5 months and 3 weeks ago\"\n\u003e\u003e timeago(Date.today.prev_day(2000), depth: 4)\n=\u003e \"5 years, 5 months, 3 weeks and 4 days ago\"\n```\n\n#### `threshold`\n\nThe 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`).\n\n```ruby\n\u003e\u003e timeago(Date.today.prev_day(366), depth: 2, threshold: 0.05)\n=\u003e \"1 year ago\"\n```\n\n#### `style`\n\nUse `:short` style for abbreviated time formats:\n\n```ruby\n\u003e\u003e timeago(Date.today.prev_day(365), style: :short)\n=\u003e \"1y ago\"\n\u003e\u003e timeago(Date.today.prev_day(30), style: :short)\n=\u003e \"1mo ago\"\n\u003e\u003e timeago(Date.today.prev_day(7), style: :short)\n=\u003e \"1w ago\"\n```\n\nUse `:array` style for structured data:\n\n```ruby\n\u003e\u003e timeago(Date.today.prev_day(365), style: :array)\n=\u003e [\"1 year\"]\n\u003e\u003e timeago(Date.today.prev_day(160), style: :array)\n=\u003e [\"5 months\", \"1 week\"]\n\u003e\u003e timeago(Date.today.prev_day(160), style: :array, locale: :es)\n=\u003e [\"5 meses\", \"1 semana\"]\n```\n\nUse `:hash` style for structured hash data:\n\n```ruby\n\u003e\u003e timeago(Date.today.prev_day(365), style: :hash)\n=\u003e {:years=\u003e1}\n\u003e\u003e timeago(Date.today.prev_day(160), style: :hash)\n=\u003e {:months=\u003e5, :weeks=\u003e1}\n\u003e\u003e timeago(Date.today.prev_day(160), style: :hash, locale: :es)\n=\u003e {:meses=\u003e5, :semanas=\u003e1}\n```\n\n#### `only`\n\nUse the `only` option to accumulate all time into a single unit. Supported values are `:years`, `:months`, `:weeks`, and `:days`:\n\n```ruby\n\u003e\u003e timeago(Date.today.prev_day(365), only: :weeks)\n=\u003e \"52 weeks ago\"\n\u003e\u003e timeago(Date.today.prev_day(365), only: :months)\n=\u003e \"12 months ago\"\n\u003e\u003e timeago(Date.today.prev_day(100), only: :weeks)\n=\u003e \"14 weeks ago\"\n\u003e\u003e timeago(Date.today.prev_day(500), only: :days)\n=\u003e \"500 days ago\"\n\u003e\u003e timeago(Date.today.prev_day(365), only: :weeks, style: :short)\n=\u003e \"52w ago\"\n\u003e\u003e timeago(Date.today.prev_day(365), only: :months, locale: :es)\n=\u003e \"hace 12 meses\"\n\u003e\u003e timeago(Date.today.prev_day(365), only: :months, style: :hash)\n=\u003e {:months=\u003e12}\n```\n\n## Localization\n\nBy default, `jekyll-timego` already provides translations for some languages. You can check the list [here](lib/locales/). However, you are able to provide your own translations, or even override the originals, easily.\n\nThis project uses the [mini_i18n](https://github.com/markets/mini_i18n) gem under the hood to deal with translations. You can read further about all options in [its docs](https://github.com/markets/mini_i18n#usage). Example:\n\n```ruby\nMiniI18n.configure do |config|\n  config.load_translations('/path_to_your_translations_files/*.yml')\n  config.default_locale = :es\nend\n```\n\nIf you want to contribute and support more default languages, please feel free to send a pull request.\n\n## CLI\n\nYou can also use `jekyll-timeago` from the command line:\n\n```\n\u003e timeago --help\n\u003e timeago 2016-1-1\n2 years and 6 months ago\n\u003e timeago 2016-1-1 --locale fr\nil y a environ 2 années et 6 mois\n\u003e timeago 2016-1-1 2018-1-1 --style short\n2y ago\n\u003e timeago 2016-1-1 2018-1-1 -l es -s short\nhace 2a y 1d\n\u003e timeago 2016-1-1 2018-1-1 --style hash\n{:years=\u003e2, :days=\u003e1}\n\u003e timeago 2016-1-1 2018-1-1 --only weeks\n104 weeks ago\n\u003e timeago 2016-1-1 2018-1-1 --only months -s short\n24mo ago\n```\n\n### Console\n\nStarts a custom IRB session with the `timeago` method included:\n\n```\n\u003e timeago --console\n\u003e\u003e timeago(Date.today)\n=\u003e \"today\"\n```\n\n## Jekyll integration\n\nYou have different options to install and use `jekyll-timeago` into your Jekyll project:\n\n- **Via Jekyll plugin system**\n\nInstall the `gem` to your system:\n\n```\n\u003e gem install jekyll-timeago\n```\n\nIn 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:\n\n```yaml\nplugins:\n  - jekyll-timeago\n```\n\n- **Via Bundler**\n\nAdd this gem to your `Gemfile` and run `bundle install`:\n\n```ruby\ngroup :jekyll_plugins do\n  gem 'jekyll-timeago'\nend\n```\n\n### Usage\n\n**Liquid Filter**:\n\n```html\n\u003cp\u003e{{ page.date | timeago }}\u003c/p\u003e\n\u003cp\u003e{{ page.date | timeago: '2020-1-1' }}\u003c/p\u003e\n```\n\n**Liquid Tag**:\n\n```html\n\u003cp\u003e{% timeago 2000-1-1 %}\u003c/p\u003e\n\u003cp\u003e{% timeago 2000-1-1 2010-1-1 %}\u003c/p\u003e\n```\n\n### Configuration\n\nIn your `_config.yml` file, you can customize the following options:\n\n```yaml\njekyll_timeago:\n  depth: 2\n  translations_path: '/path_to_your_translations/*.yaml'\n  default_locale: 'en'\n  fallbacks: true\n  available_locales:\n    - 'en'\n    - 'es'\n    - 'fr'\n```\n\nAlso, you can set a different language per page using the [Front Matter](https://jekyllrb.com/docs/frontmatter/) functionality:\n\n```yaml\n---\nlocale: 'es'\n---\n```\n\n## Development\n\nAny kind of feedback, bug report, idea or enhancement are really appreciated.\n\nTo 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:\n\n```\n\u003e bundle exec rspec\n```\n\n## License\n\nCopyright (c) Marc Anguera. Jekyll-Timeago is released under the [MIT](LICENSE) License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkets%2Fjekyll-timeago","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkets%2Fjekyll-timeago","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkets%2Fjekyll-timeago/lists"}