jekyll-unirate

CI Gem Version

Currency conversion and live exchange rates for Jekyll, powered by the UniRate API.

jekyll-unirate fetches one exchange-rate snapshot at build time and exposes Liquid filters and tags to convert amounts, format prices, and look up rates anywhere in your site. Every cross-rate is derived on demand from a single base snapshot, so one HTTP request covers all currency pairs — and if the API is briefly unreachable, your build still succeeds with amounts rendered unconverted rather than failing.

Installation

Add the gem to your site's Gemfile, in the :jekyll_plugins group:

group :jekyll_plugins do
  gem "jekyll-unirate"
end

Then bundle install. (Or add jekyll-unirate to the plugins: list in _config.yml if you manage plugins there.)

Configuration

Configure the plugin under a unirate: key in _config.yml:

unirate:
  base: USD                 # currency the rate snapshot is fetched against
  default_currency: USD     # display currency for formatting helpers
  base_url: https://api.unirateapi.com
  timeout: 30
  # api_key: ...            # prefer the UNIRATE_API_KEY env var (see below)

API key

Get a free key at unirateapi.com. Provide it via the UNIRATE_API_KEY environment variable so it never gets committed to your site repository:

UNIRATE_API_KEY=your-key bundle exec jekyll build

The env var takes precedence; unirate.api_key in _config.yml is a fallback. If no key is configured, the build still runs — helpers just render amounts unconverted and a warning is logged.

Usage

Filters

{{ "USD" | unirate_rate: "EUR" }}          {%- comment %} 0.92 {% endcomment -%}
{{ 100   | unirate_convert: "USD", "EUR" }} {%- comment %} 92.0 {% endcomment -%}
{{ 92.5  | unirate_money: "EUR" }}          {%- comment %} €92.50 {% endcomment -%}
{{ 100   | unirate_price: "USD", "EUR" }}   {%- comment %} €92.00 {% endcomment -%}
Filter Returns
unirate_rate: from, to Numeric exchange rate (empty if unknown)
unirate_convert: from, to Converted number (falls back to the input amount)
unirate_money: currency A bare amount formatted with the currency symbol
unirate_price: from, to Converted and formatted in the target currency

Front-matter variables work as arguments too:

{{ page.price | unirate_price: page.base_currency, site.currency }}

Tags

{% unirate_rate USD EUR %}            {%- comment %} 0.92 {% endcomment -%}
{% unirate_convert 100 USD EUR %}     {%- comment %} 92.0 {% endcomment -%}
{% unirate_price 100 USD EUR %}       {%- comment %} €92.00 {% endcomment -%}

Tag arguments may be literals (quoted or bare) or Liquid variables resolved against the current context:

{% unirate_price item.price USD page.currency %}

Raw rate data

The full snapshot is also published to site.data["unirate"] so you can iterate it directly:

Rates as of build (base {{ site.data.unirate.base }}):
{% for pair in site.data.unirate.rates %}
  1 {{ site.data.unirate.base }} = {{ pair[1] }} {{ pair[0] }}
{% endfor %}

site.data.unirate.updated is true when rates loaded successfully and false when the fetch was skipped or failed.

Formatting

unirate_money / unirate_price use a lightweight built-in formatter (symbol table + #,##0.00 grouping, with zero-decimal currencies like JPY handled). It is intentionally dependency-free and not a substitute for full locale-aware i18n — for anything richer, use unirate_convert to get the number and format it yourself.

Graceful degradation

This plugin is built to never break your build:

  • No API key → fetch skipped, amounts render unconverted, warning logged.
  • API error / network failure → warning logged, build continues, helpers fall back to the input amount.

Mapped API responses: 401 (bad/missing key), 403 (Pro-gated endpoint), 404 (unknown currency), 429 (rate limit), plus network and malformed-response errors.

Development

bundle install
bundle exec rspec      # WebMock-based mock tests
bundle exec rubocop

Other UniRate clients

UniRate ships official client libraries and framework integrations across the ecosystem. The repos below are all maintained under the UniRate-API org.

Get a free API key at unirateapi.com.

License

MIT — see LICENSE.