jekyll-unirate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 545b7fd8b44a778643ca5ac64a96481a5b36f69db89711d0aa5e78516aa3df56
+  data.tar.gz: 65c8702502582332fddd832e698c5d368b365b237b9aa4ad5be3cfd6ec3e6eed
+SHA512:
+  metadata.gz: 49fc0bbf2d4de414e2ef9c615be0849e81efdd53c9294760e0df16cc124722317b9cddbe5bd304ca5b0e798809f641d19673fbd56dc5cc57010df2403494e5fe
+  data.tar.gz: 6a7bb07ee5cda9a8f0ccac9d42221d38f7c8f37c0b4bf868d98a0c1d4e1fc6c0fd7cc1ef9cc7ad981af2178501cfea9c24be27f1d3a1bc52b4bd09ea3d4ccbd7

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-19
+
+### Added
+
+- Initial release.
+- Build-time `Jekyll::Generator` that fetches one single-base exchange-rate
+  snapshot from the UniRate API and exposes it to the build.
+- Liquid filters: `unirate_rate`, `unirate_convert`, `unirate_money`,
+  `unirate_price`.
+- Liquid tags: `{% unirate_rate %}`, `{% unirate_convert %}`,
+  `{% unirate_price %}`.
+- `site.data["unirate"]` rate map for direct template iteration.
+- Cross-rates derived on demand from the single-base snapshot.
+- Graceful degradation: a failed fetch logs a warning and never breaks the
+  build; helpers fall back to unconverted amounts.
+
+[0.1.0]: https://github.com/UniRate-API/jekyll-unirate/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unirate Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+# jekyll-unirate
+
+[![CI](https://github.com/UniRate-API/jekyll-unirate/actions/workflows/ci.yml/badge.svg)](https://github.com/UniRate-API/jekyll-unirate/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/jekyll-unirate)](https://rubygems.org/gems/jekyll-unirate)
+
+Currency conversion and live exchange rates for [Jekyll](https://jekyllrb.com),
+powered by the [UniRate API](https://unirateapi.com).
+
+`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:
+
+```ruby
+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`:
+
+```yaml
+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](https://unirateapi.com). Provide it via the
+`UNIRATE_API_KEY` environment variable so it never gets committed to your site
+repository:
+
+```bash
+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
+
+```liquid
+{{ "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:
+
+```liquid
+{{ page.price | unirate_price: page.base_currency, site.currency }}
+```
+
+### Tags
+
+```liquid
+{% 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:
+
+```liquid
+{% 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:
+
+```liquid
+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
+
+```bash
+bundle install
+bundle exec rspec      # WebMock-based mock tests
+bundle exec rubocop
+```
+
+<!-- unirate-ecosystem-footer:start -->
+## Other UniRate clients
+
+UniRate ships official client libraries and framework integrations across the
+ecosystem. The repos below are all maintained under the
+[UniRate-API](https://github.com/UniRate-API) org.
+
+- **Languages:** [Python](https://github.com/UniRate-API/unirate-api-python) · [Node.js / TypeScript](https://github.com/UniRate-API/unirate-api-nodejs) · [Go](https://github.com/UniRate-API/unirate-api-go) · [Rust](https://github.com/UniRate-API/unirate-api-rust) · [Java](https://github.com/UniRate-API/unirate-api-java) · [Ruby](https://github.com/UniRate-API/unirate-api-ruby) · [PHP](https://github.com/UniRate-API/unirate-api-php) · [.NET](https://github.com/UniRate-API/unirate-api-dotnet) · [Swift](https://github.com/UniRate-API/unirate-api-swift)
+- **Web frameworks:** [NestJS](https://github.com/UniRate-API/nestjs-unirate) · [Next.js](https://github.com/UniRate-API/next-unirate) · [Nuxt](https://github.com/UniRate-API/nuxt-unirate) · [SvelteKit](https://github.com/UniRate-API/sveltekit-unirate) · [Django / Wagtail](https://github.com/UniRate-API/wagtail-unirate) · [FastAPI](https://github.com/UniRate-API/fastapi-unirate) · [Flask](https://github.com/UniRate-API/flask-unirate) · [React](https://github.com/UniRate-API/react-unirate) · [Vue](https://github.com/UniRate-API/vue-unirate) · [tRPC](https://github.com/UniRate-API/trpc-unirate)
+- **Static-site generators:** [Astro](https://github.com/UniRate-API/astro-unirate) · [Eleventy](https://github.com/UniRate-API/eleventy-unirate) · [Hugo](https://github.com/UniRate-API/hugo-unirate) · [Jekyll](https://github.com/UniRate-API/jekyll-unirate)
+- **Data / orchestration:** [Airflow](https://github.com/UniRate-API/airflow-provider-unirate) · [dbt](https://github.com/UniRate-API/dbt-unirate) · [LangChain](https://github.com/UniRate-API/langchain-unirate)
+- **Workflow / no-code:** [n8n](https://github.com/UniRate-API/n8n-nodes-unirate) · [Google Sheets](https://github.com/UniRate-API/unirate-sheets) · [MCP server](https://github.com/UniRate-API/unirate-mcp)
+- **Editors / tools:** [VS Code](https://github.com/UniRate-API/vscode-unirate) · [Obsidian](https://github.com/UniRate-API/obsidian-currency)
+- **Specialty bridges:** [NodaMoney (.NET)](https://github.com/UniRate-API/UniRateApi.NodaMoney) · [money gem (Ruby)](https://github.com/UniRate-API/money-unirate-api) · [Laravel Money](https://github.com/UniRate-API/laravel-money-unirate)
+
+Get a free API key at [unirateapi.com](https://unirateapi.com).
+<!-- unirate-ecosystem-footer:end -->
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/jekyll-unirate.gemspec

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "jekyll/unirate/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "jekyll-unirate"
+  spec.version       = Jekyll::Unirate::VERSION
+  spec.authors       = ["Unirate Team"]
+  spec.email         = ["admin@unirateapi.com"]
+
+  spec.summary       = "UniRate currency conversion for Jekyll — Liquid tags & filters."
+  spec.description   = "A Jekyll plugin backed by the UniRate API " \
+                       "(https://unirateapi.com). Fetches one exchange-rate " \
+                       "snapshot at build time and exposes Liquid filters and " \
+                       "tags to convert, format, and look up currency rates, " \
+                       "with cross-rates derived on demand. Fails gracefully so " \
+                       "an API blip never breaks the build."
+  spec.homepage      = "https://github.com/UniRate-API/jekyll-unirate"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "bug_tracker_uri" => "#{spec.homepage}/issues",
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://unirateapi.com",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "jekyll-unirate.gemspec"
+  ]
+  spec.require_paths = ["lib"]
+
+  # Jekyll is the host framework, always present in a Jekyll site. Net/HTTP and
+  # JSON come from the standard library, so there are no other runtime deps.
+  spec.add_dependency "jekyll", ">= 3.7", "< 5.0"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.60"
+  spec.add_development_dependency "webmock", "~> 3.19"
+end

data/lib/jekyll/unirate/client.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "version"
+
+module Jekyll
+  module Unirate
+    # Raised for any UniRate-specific failure: a network problem, an auth
+    # error, a Pro-gated endpoint, or an unexpected response shape. The
+    # generator rescues this and logs a warning so a transient API blip never
+    # breaks the site build.
+    class Error < StandardError; end
+
+    # Minimal stdlib-only HTTP client for the UniRate API
+    # (https://unirateapi.com). Pulls a single-base rate snapshot from
+    # `GET /api/rates`; cross-rates are derived from it by {Snapshot}.
+    #
+    # Zero runtime dependencies beyond Ruby's standard library — `net/http`
+    # and `json`. No third-party HTTP gem, so nothing extra to audit.
+    class Client
+      DEFAULT_BASE_URL = "https://api.unirateapi.com"
+      DEFAULT_TIMEOUT = 30
+
+      def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+        raise Error, "UniRate API key is required" if api_key.nil? || api_key.to_s.empty?
+
+        @api_key = api_key
+        @base_url = base_url
+        @timeout = timeout
+      end
+
+      # Fetch a single-base snapshot. Returns a {Snapshot} whose `rates` map is
+      # { "EUR" => BigDecimal, ... } expressed against +base+.
+      def fetch_snapshot(base)
+        base = base.to_s.upcase
+        body = http_get("/api/rates", "from" => base)
+        rates = body["rates"]
+        raise Error, 'Unexpected UniRate response: missing "rates"' unless rates.is_a?(Hash)
+
+        parsed = rates.each_with_object({}) do |(code, value), out|
+          out[code.to_s.upcase] = BigDecimal(value.to_s)
+        end
+        Snapshot.new(base: base, rates: parsed)
+      end
+
+      private
+
+      def http_get(path, params)
+        uri = URI.parse(@base_url)
+        uri.path = path
+        uri.query = URI.encode_www_form(params.merge("api_key" => @api_key))
+
+        req = Net::HTTP::Get.new(uri)
+        req["Accept"] = "application/json"
+        req["User-Agent"] = "jekyll-unirate/#{VERSION}"
+
+        parse(perform(uri, req))
+      end
+
+      def perform(uri, req)
+        Net::HTTP.start(uri.hostname, uri.port,
+                        use_ssl: uri.scheme == "https",
+                        open_timeout: @timeout,
+                        read_timeout: @timeout) { |http| http.request(req) }
+      rescue StandardError => e
+        raise Error, "Network error talking to UniRate: #{e.message}"
+      end
+
+      def parse(response)
+        status = response.code.to_i
+        case status
+        when 200..299
+          JSON.parse(response.body.to_s)
+        when 401 then raise Error, "Missing or invalid UniRate API key (HTTP 401)"
+        when 403 then raise Error, "This UniRate endpoint requires a Pro subscription (HTTP 403)"
+        when 404 then raise Error, "Currency not found or no data available (HTTP 404)"
+        when 429 then raise Error, "UniRate rate limit exceeded (HTTP 429)"
+        else
+          raise Error, "UniRate API error (HTTP #{status}): #{response.body}"
+        end
+      rescue JSON::ParserError => e
+        raise Error, "Failed to parse UniRate response: #{e.message}"
+      end
+    end
+  end
+end

data/lib/jekyll/unirate/config.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Unirate
+    # Resolves plugin configuration from `_config.yml` (the `unirate:` key)
+    # layered over environment variables and sensible defaults.
+    #
+    #   unirate:
+    #     base: USD                 # currency the snapshot is fetched against
+    #     default_currency: USD     # display currency for one-arg helpers
+    #     base_url: https://api.unirateapi.com
+    #     timeout: 30
+    #     # api_key: prefer the UNIRATE_API_KEY env var over committing a key
+    #
+    # The API key resolves from (in order): the UNIRATE_API_KEY env var, then
+    # `unirate.api_key` in _config.yml. Keeping it in the environment avoids
+    # checking a secret into the site repo.
+    class Config
+      DEFAULTS = {
+        "base" => "USD",
+        "default_currency" => "USD",
+        "base_url" => Client::DEFAULT_BASE_URL,
+        "timeout" => Client::DEFAULT_TIMEOUT
+      }.freeze
+
+      def initialize(site_config = {})
+        raw = site_config && site_config["unirate"]
+        @settings = DEFAULTS.merge(stringify(raw))
+      end
+
+      def api_key
+        env = ENV.fetch("UNIRATE_API_KEY", nil)
+        return env unless env.nil? || env.empty?
+
+        @settings["api_key"]
+      end
+
+      def base = @settings["base"].to_s.upcase
+      def default_currency = @settings["default_currency"].to_s.upcase
+      def base_url = @settings["base_url"]
+      def timeout = @settings["timeout"]
+
+      private
+
+      def stringify(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/jekyll/unirate/filters.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+require_relative "snapshot"
+require_relative "formatter"
+
+module Jekyll
+  module Unirate
+    # Liquid filters for use in any Jekyll template. All are prefixed
+    # `unirate_` to avoid clashing with site- or theme-defined filters.
+    #
+    #   {{ 100   | unirate_convert: "USD", "EUR" }}   => 92.0
+    #   {{ "USD" | unirate_rate: "EUR" }}             => 0.92
+    #   {{ 92.5  | unirate_money: "EUR" }}            => "€92.50"
+    #   {{ 100   | unirate_price: "USD", "EUR" }}     => "€92.00"
+    #
+    # Every filter degrades gracefully when no snapshot is available or a pair
+    # is missing: `unirate_convert`/`unirate_price` fall back to the input
+    # amount (so a price still renders), `unirate_rate` returns nil. This keeps
+    # a transient API problem from breaking the rendered page.
+    module Filters
+      # Numeric exchange rate from +from+ to +to+ (Float), or nil if unknown.
+      def unirate_rate(from, to)
+        snapshot = Snapshot.current
+        return nil if snapshot.nil?
+
+        rate = snapshot.rate(from, to)
+        rate&.to_f
+      end
+
+      # Convert +amount+ from +from+ to +to+ (Float). Falls back to the input
+      # amount unchanged when the rate is unavailable.
+      def unirate_convert(amount, from, to)
+        snapshot = Snapshot.current
+        return to_number(amount) if snapshot.nil?
+
+        converted = snapshot.convert(amount, from, to)
+        converted ? converted.to_f : to_number(amount)
+      end
+
+      # Format a bare numeric +amount+ in +currency+ (e.g. "€92.50").
+      def unirate_money(amount, currency)
+        Formatter.format(amount, currency)
+      end
+
+      # Convert +amount+ from +from+ to +to+ and format it in +to+. Falls back
+      # to formatting the input amount in +to+ when no rate is available.
+      def unirate_price(amount, from, to)
+        Formatter.format(unirate_convert(amount, from, to), to)
+      end
+
+      private
+
+      def to_number(amount)
+        Float(amount)
+      rescue ArgumentError, TypeError
+        amount
+      end
+    end
+  end
+end
+
+Liquid::Template.register_filter(Jekyll::Unirate::Filters)

data/lib/jekyll/unirate/formatter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Jekyll
+  module Unirate
+    # Lightweight currency formatter. Ruby's stdlib has no locale-aware money
+    # formatting and we deliberately avoid a heavy dependency (e.g. the `money`
+    # gem) for a static-site helper, so this is a pragmatic symbol table plus
+    # fixed grouping: `#,##0.00` with the symbol prefixed (or the ISO code when
+    # the symbol is unknown). Good enough for prices on a static page; not a
+    # substitute for full i18n.
+    module Formatter
+      SYMBOLS = {
+        "USD" => "$", "EUR" => "€", "GBP" => "£", "JPY" => "¥",
+        "CNY" => "¥", "AUD" => "A$", "CAD" => "C$", "CHF" => "CHF ",
+        "HKD" => "HK$", "NZD" => "NZ$", "SEK" => "kr ", "KRW" => "₩",
+        "SGD" => "S$", "NOK" => "kr ", "MXN" => "MX$", "INR" => "₹",
+        "RUB" => "₽", "ZAR" => "R", "TRY" => "₺", "BRL" => "R$",
+        "TWD" => "NT$", "DKK" => "kr ", "PLN" => "zł ",
+        "THB" => "฿", "IDR" => "Rp", "HUF" => "Ft ", "CZK" => "Kč ",
+        "ILS" => "₪", "PHP" => "₱", "AED" => "د.إ ",
+        "SAR" => "ر.س ", "MYR" => "RM", "RON" => "lei ",
+        "NGN" => "₦", "BTC" => "₿"
+      }.freeze
+
+      # Currencies conventionally shown without decimal places.
+      ZERO_DECIMAL = %w[JPY KRW HUF IDR CLP VND ISK].freeze
+
+      module_function
+
+      # Format +amount+ in +currency+. Returns a String such as "€1,234.50".
+      def format(amount, currency, decimals: nil)
+        currency = currency.to_s.upcase
+        decimals ||= ZERO_DECIMAL.include?(currency) ? 0 : 2
+        rounded = BigDecimal(amount.to_s).round(decimals)
+        sign = rounded.negative? ? "-" : ""
+        number = group(rounded.abs, decimals)
+        symbol = SYMBOLS[currency]
+        # Sign goes outside the symbol ("-$1,234.50"), the conventional form.
+        symbol ? "#{sign}#{symbol}#{number}" : "#{sign}#{number} #{currency}"
+      end
+
+      # Group a non-negative decimal with thousands separators and fixed
+      # decimals. Calls Kernel.format explicitly — the bareword `format` would
+      # resolve to this module's own currency-formatting method.
+      def group(value, decimals)
+        whole, frac = Kernel.format("%.#{decimals}f", value).split(".")
+        whole = whole.reverse.gsub(/(\d{3})(?=\d)/, '\1,').reverse
+        frac ? "#{whole}.#{frac}" : whole
+      end
+    end
+  end
+end

data/lib/jekyll/unirate/generator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "jekyll"
+
+require_relative "client"
+require_relative "snapshot"
+require_relative "config"
+
+module Jekyll
+  module Unirate
+    # Build-time generator that fetches ONE single-base UniRate snapshot and
+    # makes it available to the rest of the build. Runs early (high priority)
+    # so the snapshot is ready before any page renders.
+    #
+    # It does two things:
+    #   1. sets {Snapshot.current}, which the Liquid filters and tags read; and
+    #   2. populates `site.data["unirate"]` so templates can iterate the raw
+    #      rate map directly (`{% for pair in site.data.unirate.rates %}`).
+    #
+    # A failed fetch is logged as a warning and never raised — the build
+    # continues and helpers degrade to unconverted amounts. This is the same
+    # "never break the build" contract the Hugo/Eleventy/Astro integrations use.
+    class Generator < Jekyll::Generator
+      priority :high
+
+      def generate(site)
+        config = Config.new(site.config)
+        Jekyll::Unirate.default_currency = config.default_currency
+
+        key = config.api_key
+        if key.nil? || key.to_s.empty?
+          Jekyll.logger.warn("UniRate:",
+                             "no API key (set UNIRATE_API_KEY or unirate.api_key in _config.yml); " \
+                             "skipping rate fetch")
+          return store_empty(site, config.base)
+        end
+
+        load_rates(site, config)
+      end
+
+      private
+
+      def load_rates(site, config)
+        client = Client.new(api_key: config.api_key, base_url: config.base_url, timeout: config.timeout)
+        snapshot = client.fetch_snapshot(config.base)
+        Snapshot.current = snapshot
+        site.data["unirate"] = {
+          "base" => snapshot.base,
+          "rates" => snapshot.rates.transform_values(&:to_f),
+          "updated" => true
+        }
+        Jekyll.logger.info("UniRate:", "loaded #{snapshot.rates.size} rates (base #{snapshot.base})")
+      rescue Error => e
+        Jekyll.logger.warn("UniRate:",
+                           "rate fetch failed (#{e.message}); pages will render with unconverted amounts")
+        store_empty(site, config.base)
+      end
+
+      def store_empty(site, base)
+        site.data["unirate"] = { "base" => base, "rates" => {}, "updated" => false }
+      end
+    end
+  end
+end

data/lib/jekyll/unirate/snapshot.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Jekyll
+  module Unirate
+    # An immutable single-base rate snapshot. One HTTP call to UniRate fetches
+    # base->code rates; every cross-rate is derived from this snapshot on
+    # demand (`rate(F,T) = base->T / base->F`), so the whole build shares one
+    # frozen view of the market and no per-pair caching can go stale.
+    class Snapshot
+      attr_reader :base, :rates
+
+      # Process-wide current snapshot, set by {Generator} at build time and
+      # read by the Liquid filters and tags. nil until the generator runs (or
+      # if the fetch failed) — callers must degrade gracefully when it is.
+      class << self
+        attr_accessor :current
+      end
+
+      # @param base [String] base currency the rates are expressed against
+      # @param rates [Hash{String=>BigDecimal}] base->code rate map
+      def initialize(base:, rates:)
+        @base = base.to_s.upcase
+        @rates = rates.freeze
+        freeze
+      end
+
+      # All currency codes available in this snapshot (including the base),
+      # sorted — handy for `{% for c in ... %}` style template loops.
+      def currencies
+        ([@base] + @rates.keys).uniq.sort
+      end
+
+      # Cross-rate from +from+ to +to+ as a BigDecimal, or nil if either
+      # currency is absent from the snapshot.
+      def rate(from, to)
+        from = from.to_s.upcase
+        to = to.to_s.upcase
+        return BigDecimal(1) if from == to
+
+        from_rate = base_rate(from)
+        to_rate = base_rate(to)
+        return nil if from_rate.nil? || to_rate.nil?
+
+        to_rate / from_rate
+      end
+
+      # Convert +amount+ from +from+ to +to+ as a BigDecimal, or nil if no
+      # rate is available for the pair.
+      def convert(amount, from, to)
+        r = rate(from, to)
+        return nil if r.nil?
+
+        BigDecimal(amount.to_s) * r
+      end
+
+      private
+
+      # base->iso rate (1 for the base itself); nil if not present.
+      def base_rate(iso)
+        return BigDecimal(1) if iso == @base
+
+        @rates[iso]
+      end
+    end
+  end
+end

data/lib/jekyll/unirate/tags.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+require_relative "snapshot"
+require_relative "formatter"
+
+module Jekyll
+  module Unirate
+    # Shared parsing/resolution for the UniRate Liquid tags. Each tag takes
+    # space-separated arguments that may be string/number literals OR Liquid
+    # variables resolved against the render context:
+    #
+    #   {% unirate_rate USD EUR %}
+    #   {% unirate_convert 100 USD EUR %}
+    #   {% unirate_price item.price USD EUR %}
+    #   {% unirate_price 100 USD page.currency %}
+    class BaseTag < Liquid::Tag
+      def initialize(tag_name, markup, tokens)
+        super
+        @args = markup.strip.split(/\s+/)
+      end
+
+      private
+
+      # Resolve a single argument: a quoted/bare literal, or a context lookup.
+      def resolve(arg, context)
+        return nil if arg.nil?
+
+        if arg =~ /\A["'](.*)["']\z/
+          ::Regexp.last_match(1)
+        else
+          looked_up = context[arg]
+          looked_up.nil? ? arg : looked_up
+        end
+      end
+
+      def snapshot
+        Snapshot.current
+      end
+    end
+
+    # `{% unirate_rate FROM TO %}` -> numeric rate, or empty string if unknown.
+    class RateTag < BaseTag
+      def render(context)
+        from = resolve(@args[0], context)
+        to = resolve(@args[1], context)
+        return "" if snapshot.nil?
+
+        rate = snapshot.rate(from, to)
+        rate ? rate.to_f.to_s : ""
+      end
+    end
+
+    # `{% unirate_convert AMOUNT FROM TO %}` -> converted number (falls back to
+    # the input amount when no rate is available).
+    class ConvertTag < BaseTag
+      def render(context)
+        amount = resolve(@args[0], context)
+        from = resolve(@args[1], context)
+        to = resolve(@args[2], context)
+        return amount.to_s if snapshot.nil?
+
+        converted = snapshot.convert(amount, from, to)
+        (converted ? converted.to_f : amount).to_s
+      end
+    end
+
+    # `{% unirate_price AMOUNT FROM TO %}` -> converted amount formatted in TO.
+    class PriceTag < BaseTag
+      def render(context)
+        amount = resolve(@args[0], context)
+        from = resolve(@args[1], context)
+        to = resolve(@args[2], context)
+        value = snapshot ? (snapshot.convert(amount, from, to) || amount) : amount
+        Formatter.format(value, to)
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag("unirate_rate", Jekyll::Unirate::RateTag)
+Liquid::Template.register_tag("unirate_convert", Jekyll::Unirate::ConvertTag)
+Liquid::Template.register_tag("unirate_price", Jekyll::Unirate::PriceTag)

data/lib/jekyll/unirate/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Unirate
+    VERSION = "0.1.0"
+  end
+end

data/lib/jekyll/unirate.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "unirate/version"
+
+module Jekyll
+  # UniRate currency integration for Jekyll. See {Generator}, {Filters} and the
+  # tag classes for the build-time and template-side entry points.
+  module Unirate
+    class << self
+      # Display currency used by one-argument helpers; set by {Generator} from
+      # `unirate.default_currency` in _config.yml. Defaults to "USD".
+      attr_writer :default_currency
+
+      def default_currency
+        @default_currency || "USD"
+      end
+    end
+  end
+end
+
+require_relative "unirate/client"
+require_relative "unirate/snapshot"
+require_relative "unirate/formatter"
+require_relative "unirate/config"
+require_relative "unirate/filters"
+require_relative "unirate/tags"
+require_relative "unirate/generator"

data/lib/jekyll-unirate.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Convenience entry point matching the gem name, so `require "jekyll-unirate"`
+# (and Jekyll's auto-require of `jekyll_plugins` Gemfile gems) loads everything.
+require_relative "jekyll/unirate"

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-unirate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Unirate Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+description: A Jekyll plugin backed by the UniRate API (https://unirateapi.com). Fetches
+  one exchange-rate snapshot at build time and exposes Liquid filters and tags to
+  convert, format, and look up currency rates, with cross-rates derived on demand.
+  Fails gracefully so an API blip never breaks the build.
+email:
+- admin@unirateapi.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- jekyll-unirate.gemspec
+- lib/jekyll-unirate.rb
+- lib/jekyll/unirate.rb
+- lib/jekyll/unirate/client.rb
+- lib/jekyll/unirate/config.rb
+- lib/jekyll/unirate/filters.rb
+- lib/jekyll/unirate/formatter.rb
+- lib/jekyll/unirate/generator.rb
+- lib/jekyll/unirate/snapshot.rb
+- lib/jekyll/unirate/tags.rb
+- lib/jekyll/unirate/version.rb
+homepage: https://github.com/UniRate-API/jekyll-unirate
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/UniRate-API/jekyll-unirate
+  source_code_uri: https://github.com/UniRate-API/jekyll-unirate
+  bug_tracker_uri: https://github.com/UniRate-API/jekyll-unirate/issues
+  changelog_uri: https://github.com/UniRate-API/jekyll-unirate/blob/main/CHANGELOG.md
+  documentation_uri: https://unirateapi.com
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: UniRate currency conversion for Jekyll — Liquid tags & filters.
+test_files: []