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.

PyPI Python License: MIT CI

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

Placeholder Renders
{{ unirate_rate:FROM:TO }} Current exchange rate for the pair
{{ unirate_convert:FROM:TO:AMOUNT }} AMOUNT converted at the current rate

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

Option Type Default Description
api_key str "" UniRate API key. Falls back to UNIRATE_API_KEY env var.
base_url str "" Override the API base URL (rare — self-hosted proxy).
base_currency str "USD" Default base exposed to the Jinja global.
currencies list [] Currencies of interest (informational / templates).
enable_markdown bool true Toggle Markdown placeholder substitution.
enable_jinja bool true Toggle the unirate Jinja global.
strict bool false Fail the build on any UniRate error instead of warning.
decimals int 4 Decimal places for rendered values.
timeout int 30 HTTP request timeout in seconds.

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.

Project links

Data verified by PyPI on Aug 11, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for rob.brown96cc from gravatar.com rob.brown96cc

Credits

Author: Unirate Team

GitHub Statistics

Data verified by PyPI on Aug 11, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Tags

currency exchange-rates fintech forex mkdocs mkdocs-plugin unirate vat

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_unirate-0.1.0.tar.gz (11.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mkdocs_unirate-0.1.0-py3-none-any.whl (9.4 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs_unirate-0.1.0.tar.gz.

File metadata

  • Download URL: mkdocs_unirate-0.1.0.tar.gz
  • Upload date:
  • Size: 11.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mkdocs_unirate-0.1.0.tar.gz
Algorithm Hash digest
SHA256 3a3720dbb6517b2be931c80cf79573e9957dcbb4eafb1c86833c7b7092c7045f
MD5 fb79915a16ff5f7643a44f4faed611e6
BLAKE2b-256 264d0c1cae417392b7cbb3ef59cbd54e350b579c28b58de8ea72c616970d29cf

See more details on using hashes here.

Provenance

The following attestation bundles were made for mkdocs_unirate-0.1.0.tar.gz:

Publisher: release.yml on UniRate-API/mkdocs-unirate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mkdocs_unirate-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: mkdocs_unirate-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 9.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mkdocs_unirate-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 24e08f14663807809d1f09810f172b9de61397e527326f7d7ebb23d4f292c0ab
MD5 e839ceac26c442fd0a4beef3bd7951f4
BLAKE2b-256 83ab0629b346fd59c1a0b4faebf563903a5c06da7f31b3eb31919df6ef253419

See more details on using hashes here.

Provenance

The following attestation bundles were made for mkdocs_unirate-0.1.0-py3-none-any.whl:

Publisher: release.yml on UniRate-API/mkdocs-unirate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page