mkdocs-unirate

MkDocs plugin that bakes live UniRate API exchange rates into your documentation at build time — through inline Markdown placeholders and a Jinja template global.

Installation

pip install mkdocs-unirate

Quick start

Add the plugin to mkdocs.yml:

plugins:
  - unirate:
      api_key: !ENV UNIRATE_API_KEY   # or hard-code (not recommended)
      base_currency: USD
      currencies: [EUR, GBP, JPY]
      strict: false
      decimals: 4

Then drop placeholders into any Markdown page:

1 USD = {{ unirate_rate:USD:EUR }} EUR
100 USD converts to {{ unirate_convert:USD:JPY:100 }} JPY

Build with your key in the environment:

UNIRATE_API_KEY=your_key mkdocs build

Get a free key at unirateapi.com.

Placeholders

Currency codes are case-insensitive and uppercased before the API call. Each distinct pair is fetched once per build and cached, so repeated placeholders cost a single request.

Jinja global

For pages rendered through Jinja (a custom theme, or mkdocs-macros-plugin), a unirate global is registered via on_env:

{{ unirate.base_currency }}
{{ unirate.rate("USD", "EUR") }}
{{ unirate.convert(250, "USD", "EUR") }}
{{ unirate.currencies | length }}

Configuration

Error handling

On a UniRate error (bad key, unknown currency, rate limit, service outage):

• strict: false (default) — a warning is logged and the original placeholder text is left untouched, so the build still succeeds.
• strict: true — the build aborts with a clear error message.

Status codes map to the canonical UniRate error taxonomy: 401 → authentication, 404 → invalid currency, 429 → rate limit, 403 → Pro subscription required, 503 → service unavailable.

Related UniRate clients

Other UniRate integrations: Python · Node.js · Go · Rust · Ruby · PHP · Java · Swift · .NET · FastAPI · Flask · Streamlit · Hugo · Jekyll · Eleventy · MCP Server · CLI

License

MIT — see LICENSE.