Metadata-Version: 2.4
Name: mkdocs-unirate
Version: 0.1.0
Summary: MkDocs plugin that injects live UniRate exchange rates into your docs at build time — Markdown placeholders and a Jinja global.
Project-URL: Homepage, https://github.com/UniRate-API/mkdocs-unirate
Project-URL: Repository, https://github.com/UniRate-API/mkdocs-unirate
Project-URL: Issues, https://github.com/UniRate-API/mkdocs-unirate/issues
Project-URL: Provider, https://unirateapi.com
Author: Unirate Team
License: MIT
License-File: LICENSE
Keywords: currency,exchange-rates,fintech,forex,mkdocs,mkdocs-plugin,unirate,vat
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mkdocs>=1.5.0
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

# mkdocs-unirate

MkDocs plugin that bakes live [UniRate API](https://unirateapi.com) exchange
rates into your documentation **at build time** — through inline Markdown
placeholders and a Jinja template global.

[![PyPI](https://img.shields.io/pypi/v/mkdocs-unirate)](https://pypi.org/project/mkdocs-unirate/)
[![Python](https://img.shields.io/pypi/pyversions/mkdocs-unirate)](https://pypi.org/project/mkdocs-unirate/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/UniRate-API/mkdocs-unirate/actions/workflows/test.yml/badge.svg)](https://github.com/UniRate-API/mkdocs-unirate/actions)

## Installation

```bash
pip install mkdocs-unirate
```

## Quick start

Add the plugin to `mkdocs.yml`:

```yaml
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:

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

Build with your key in the environment:

```bash
UNIRATE_API_KEY=your_key mkdocs build
```

Get a free key at [unirateapi.com](https://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`](https://github.com/fralau/mkdocs-macros-plugin)), a
`unirate` global is registered via `on_env`:

```jinja
{{ 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

<!-- unirate-ecosystem-footer:start -->
**Other UniRate integrations:**
[Python](https://github.com/UniRate-API/unirate-api-python) · [Node.js](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) · [Ruby](https://github.com/UniRate-API/unirate-api-ruby) · [PHP](https://github.com/UniRate-API/unirate-api-php) · [Java](https://github.com/UniRate-API/unirate-api-java) · [Swift](https://github.com/UniRate-API/unirate-api-swift) · [.NET](https://github.com/UniRate-API/unirate-api-dotnet) · [FastAPI](https://github.com/UniRate-API/fastapi-unirate) · [Flask](https://github.com/UniRate-API/flask-unirate) · [Streamlit](https://github.com/UniRate-API/streamlit-unirate) · [Hugo](https://github.com/UniRate-API/hugo-unirate) · [Jekyll](https://github.com/UniRate-API/jekyll-unirate) · [Eleventy](https://github.com/UniRate-API/eleventy-unirate) · [MCP Server](https://github.com/UniRate-API/unirate-mcp) · [CLI](https://github.com/UniRate-API/unirate-cli)
<!-- unirate-ecosystem-footer:end -->

## License

MIT — see [LICENSE](LICENSE).
