# @maxedapps/pi-mdr

A [Pi](https://github.com/earendil-works/pi) package that renders Markdown with the external [MDR](https://github.com/maxedapps/mdr) CLI. It registers the `/mdr` command and the `render_markdown` model tool.

## Prerequisite

Install a current MDR release that supports `--no-open` and `--out`.

macOS or Linux:

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/maxedapps/mdr/releases/latest/download/mdr-installer.sh | sh
```

Windows PowerShell:

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/maxedapps/mdr/releases/latest/download/mdr-installer.ps1 | iex"
```

Restart Pi after installation so it sees the updated `PATH`. To use a binary outside `PATH`, set `MDR_BIN` to its path before launching Pi. See [MDR releases](https://github.com/maxedapps/mdr/releases/latest).

This package does not download or bundle MDR. Installing the extension without MDR is safe: Pi continues to start normally, and `/mdr` or `render_markdown` shows installation instructions until MDR is available.

## Install

```sh
pi install npm:@maxedapps/pi-mdr
```

## `/mdr`

```text
/mdr
/mdr README.md
/mdr @docs/guide.md
/mdr "docs/a guide.md"
/mdr https://example.com/guide.md
```

With no argument, `/mdr` renders the latest completed assistant response on the active branch. One argument is treated as a whole file path or HTTP(S) URL; this is intentionally not shell-style option parsing. A matching outer quote pair is removed and a leading Pi `@` on paths is accepted.

The command uses MDR's deterministic temporary output and opens it in the default browser. It reports the generated absolute HTML path.

## `render_markdown` tool

The tool accepts:

| Field | Required | Meaning |
|---|---:|---|
| `source` | yes | `latest_response`, `text`, `path`, or `url` |
| `value` | for `text`, `path`, `url` | Raw Markdown, a file path, or an HTTP(S) URL |
| `outputPath` | no | Exact HTML destination; relative paths resolve from Pi's working directory |
| `open` | no | Open the default browser; defaults to `true` |

Examples:

```json
{ "source": "latest_response" }
{ "source": "text", "value": "# Preview" }
{ "source": "path", "value": "README.md", "open": false }
{ "source": "url", "value": "https://example.com/guide.md" }
{ "source": "text", "value": "# Publish", "outputPath": "public/preview.html", "open": false }
```

Without `outputPath`, MDR writes its deterministic cached output. With `outputPath`, MDR creates missing parent directories and atomically replaces that exact file. The tool returns the absolute HTML path and whether browser opening was requested.

## Troubleshooting

If Pi says MDR is missing, install it using the platform command above, ensure `mdr` is on `PATH`, and restart Pi. Alternatively set `MDR_BIN=/absolute/path/to/mdr`. If Pi says MDR is incompatible, update MDR from the [latest release](https://github.com/maxedapps/mdr/releases/latest); older releases may not provide the required flags.

Browser opening requires a graphical environment and configured default browser. Use `"open": false` for headless tool calls. If browser opening fails after rendering, the error retains the generated HTML path so it can be opened manually.