# mdreports — complete library (all audiences)

_Generated whole-library download. See `agent-manifest.json` → `library` for discovery._

## Table of contents

- **Overview** (`00-overview`, developers)
- **Overview** (`00-overview`, builders)
- **Packages** (`01-packages`, developers)
- **Getting Started** (`02-getting-started`, developers)
- **Getting Started** (`02-getting-started`, builders)
- **SDK** (`03-sdk`, developers)
- **CLI** (`04-cli`, developers)
- **HTTP API** (`05-api`, developers)
- **MCP** (`06-mcp`, developers)
- **Templates** (`07-templates`, developers)
- **Templates** (`07-templates`, builders)

---

# Overview — developers

# Overview — Developers

**Audience:** Engineers choosing how to consume Markdown Reports Studio.  
**Twin:** [Builders version](../builders/BOOK.md)

---

## 1. What it is

Turn Markdown into styled **PDF**, **Word (DOCX)**, **PowerPoint (PPTX)**, and **HTML** using swappable templates.

**Not** a CMS or collaborative editor — a render pipeline: Markdown in, branded document out.

One engine powers every surface: SDK, CLI, HTTP API, MCP server, Playground UI, and Studio UI.

---

## 2. Formats and surfaces

| Capability | Details |
| --- | --- |
| Formats | HTML, PDF (Playwright Chromium), DOCX, PPTX (landscape 16:9) |
| Templates | Built-ins (`clean-report`, `letter`, `technical-doc`) + your own |
| Frontmatter | YAML (e.g. `title`) fills template slots |
| Surfaces | SDK, CLI (`mdreports`), HTTP API, MCP, Playground (`:6461`), Studio (`:6463`) |

All published packages are public under `@x12i/mdreports-*` on npm.

PDF needs Chromium once per machine: `npx playwright install chromium`. Requires **Node.js 20.11+**.

---

## 3. How rendering works

1. **Parse** Markdown (including YAML frontmatter).
2. **Load template** by id — built-in or user template from disk.
3. **Inject** CSS into `layout.html` and fill slots (`<!--CONTENT-->`, `<!--TITLE-->`, meta slots).
4. **Emit** HTML string, PDF via pooled Chromium, DOCX/PPTX from the Markdown AST.

Always call `shutdown()` in SDK/long-lived processes so the browser exits cleanly.

### Known limitations

- **HTML/PDF images**: absolute `http(s)` URLs or data URIs only.
- **DOCX / PPTX images**: local paths and URLs are best-effort; failures become `[image: alt]`.
- **DOCX / PPTX code blocks**: monospace + shading — no syntax highlighting.
- **PPTX overflow**: long content under a single H1 is not auto-split (may clip).
- **Raw HTML in Markdown**: kept for HTML/PDF; dropped for DOCX and PPTX.

---

## 4. Where to go next

| Goal | Book / use case |
| --- | --- |
| First successful file | Getting Started · `pick-a-surface` |
| Which package to install | Packages · `map-packages` |
| Custom look | Templates · `author-templates` |
| Agent tools | MCP · `wire-mcp-agents` |

---

# Overview — builders

# Overview — Builders

**Audience:** Template authors and Studio users.  
**Twin:** [Developers version](../developers/BOOK.md)

---

## 1. What it is

Markdown Reports Studio turns Markdown into branded **PDF**, **DOCX**, **PPTX**, and **HTML** using templates you can browse and edit in Studio.

You do not need to change the renderer to ship a new look — author HTML+CSS templates (or draft from a screenshot) and pick them at render time.

---

## 2. Formats and surfaces

| You want… | Use |
| --- | --- |
| Try Markdown → preview / download | Playground (repo, port **6461**) |
| Browse / create / edit templates | Studio (repo, port **6463**) |
| Built-in looks without custom work | `clean-report`, `letter`, `technical-doc` |

Developers wire SDK/CLI/API/MCP; builders own template content and design screenshots for `create-from-image`.

---

## 3. How rendering works

Markdown (+ optional frontmatter `title`) is poured into a template shell. HTML/PDF share the same layout; DOCX and PPTX map structure from headings and paragraphs.

PPTX: each `#` (H1) starts a new landscape 16:9 slide.

---

## 4. Where to go next

- **Getting Started** — see the product end-to-end once.
- **Templates** — layout contract, slots, user store (`author-templates`).

---

# Packages — developers

# Packages — Developers

**Audience:** Engineers choosing which `@x12i/mdreports-*` package to install.

---

## 1. Package table

| Package | When to install |
| --- | --- |
| `@x12i/mdreports-core` | In-process HTML/PDF/DOCX/PPTX + `TemplateStore` |
| `@x12i/mdreports-cli` | Shell command `mdreports` |
| `@x12i/mdreports-api` | Network service `mdreports-api` |
| `@x12i/mdreports-api-client` | Typed `fetch` client for the HTTP API |
| `@x12i/mdreports-mcp-server` | MCP tools over stdio |
| `@x12i/mdreports-types` | Shared Zod schemas / TS types |
| `@x12i/mdreports-templates` | Rarely — pulled in by core |

Not published: `apps/playground`, `apps/studio` (run from this monorepo).

Knowledge for agents/humans: `@x12i/mdreports-docs` (this library) — install as a **devDependency** only.

---

## 2. Dependency shape

```
@x12i/mdreports-types
        ↑
@x12i/mdreports-templates ──→ @x12i/mdreports-core ──→ CLI / API / MCP
                                   ↓
                         @x12i/mdreports-api-client  (HTTP → API)
```

Core formats: **HTML**, **PDF**, **DOCX**, and landscape **PPTX** (H1 = new slide).

---

## 3. Naming note

Short names like `@x12i/core` / `@x12i/cli` are already used by another x12i project on npm, so this product publishes under `@x12i/mdreports-*`.

---

# Getting Started — developers

# Getting Started — Developers

**Audience:** First-time integrators.  
**Twin:** [Builders version](../builders/BOOK.md)

---

## 1. Prerequisites

- Node.js **20.11+**
- Chromium for PDF: `npx playwright install chromium`

---

## 2. Option A — CLI

```bash
npm install -g @x12i/mdreports-cli
npx playwright install chromium

mdreports templates list
mdreports render --in report.md --template clean-report --format pdf --out report.pdf
mdreports render --in report.md --template clean-report --format pptx --out report.pptx
```

---

## 3. Option B — SDK

```bash
npm install @x12i/mdreports-core
npx playwright install chromium
```

```ts
import { renderToPdf, renderToPptx, shutdown } from "@x12i/mdreports-core";
import { writeFile } from "node:fs/promises";

const pdf = await renderToPdf("# Hello\n\nWorld", "clean-report");
await writeFile("report.pdf", pdf);

const pptx = await renderToPptx("# Hello\n\nWorld", "clean-report");
await writeFile("report.pptx", pptx);
await shutdown();
```

---

## 4. Option C — HTTP API

```bash
npm install -g @x12i/mdreports-api
npx playwright install chromium
mdreports-api   # http://localhost:6460
```

```ts
import { ApiClient } from "@x12i/mdreports-api-client";

const client = new ApiClient({ baseUrl: "http://localhost:6460" });
const pdf = await client.renderPdf("# Hello", "clean-report");
```

---

## 5. Option D — MCP

```json
{
  "mcpServers": {
    "mdreports": {
      "command": "npx",
      "args": ["-y", "@x12i/mdreports-mcp-server"]
    }
  }
}
```

---

## 6. Built-in templates

- `clean-report` — multi-section reports
- `letter` — short correspondence
- `technical-doc` — technical documentation

Create your own with CLI `templates create-from-html` / `create-from-image`, the SDK, or Studio.

---

# Getting Started — builders

# Getting Started — Builders

**Audience:** People trying Playground/Studio before writing code.  
**Twin:** [Developers version](../developers/BOOK.md)

---

## 1. Prerequisites

From this monorepo:

```bash
pnpm install
pnpm playwright:install
pnpm build
pnpm dev
```

- Playground: **6461**
- Studio: **6463**
- API: **6460**

---

## 2. Option A — CLI

Ask a developer to install `@x12i/mdreports-cli`, or use Playground export once `pnpm dev` is running.

---

## 3. Option B — SDK

Developers embed `@x12i/mdreports-core`. Builders supply template HTML/CSS and sample Markdown.

---

## 4. Option C — HTTP API

Studio and Playground talk to the local API. Optional `MDREPORTS_API_KEY` protects non-health routes.

---

## 5. Option D — MCP

Agents can render and create templates when the MCP server is configured — useful for “turn this Markdown into a PDF” workflows.

---

## 6. Built-in templates

Start with `clean-report`, then clone look-and-feel via Studio create-from-HTML or create-from-image (`ANTHROPIC_API_KEY` required for image drafts).

---

# SDK — developers

# SDK — Developers

**Audience:** Engineers embedding `@x12i/mdreports-core` in Node.js.

---

## 1. Install

```bash
npm install @x12i/mdreports-core
npx playwright install chromium
```

---

## 2. Render

```ts
import { renderToHtml, renderToPdf, renderToDocx, renderToPptx, shutdown } from "@x12i/mdreports-core";

const md = `---
title: Q1 Report
---

# Summary

Body here.
`;

const { html, title } = await renderToHtml(md, "clean-report");
const pdf = await renderToPdf(md, "clean-report", {
  pdf: { format: "Letter", landscape: false }
});
const docx = await renderToDocx(md, "technical-doc");
const pptx = await renderToPptx(md, "clean-report"); // landscape 16:9; each H1 = new slide

await shutdown();
```

Always call `shutdown()` when your process is done (or on SIGTERM in long-lived servers) so Playwright exits cleanly.

---

## 3. Template store

```ts
import { TemplateStore } from "@x12i/mdreports-core";

const store = new TemplateStore({
  templatesDir: "./my-templates" // optional; else MDREPORTS_TEMPLATES_DIR or ~/.mdreports/templates
});

const all = await store.list();
const one = await store.get("clean-report");

await store.createFromHtml({
  id: "brand-report",
  name: "Brand Report",
  layoutHtml: "<!doctype html><html><head></head><body><main><!--CONTENT--></main></body></html>",
  stylesCss: "main { max-width: 720px; margin: 0 auto; }"
});

await store.update("brand-report", { name: "Brand Report v2" });
await store.delete("brand-report");
```

Built-in templates cannot be updated or deleted.

---

## 4. AI template from image

```ts
import { readFile } from "node:fs/promises";
import { createTemplateFromImage, shutdown } from "@x12i/mdreports-core";

const imageBuffer = await readFile("design.png");
await createTemplateFromImage({
  id: "from-design",
  name: "From Design",
  imageBuffer,
  imageMediaType: "image/png",
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!
});
await shutdown();
```

---

# CLI — developers

# CLI — Developers

**Audience:** Engineers using the `mdreports` binary.

---

## 1. Install

```bash
npm install -g @x12i/mdreports-cli
npx playwright install chromium
```

Binary name: `mdreports`.

---

## 2. Render

```bash
mdreports render --in report.md --template clean-report --format pdf --out report.pdf
mdreports render --in report.md --template letter --format docx
mdreports render --in report.md --template clean-report --format pptx
mdreports render --in report.md --template technical-doc --format html
```

---

## 3. Templates

```bash
mdreports templates list
mdreports templates list --json
mdreports templates show clean-report
mdreports templates create-from-html --id my-layout --name "My Layout" \
  --layout layout.html --styles styles.css
mdreports templates create-from-image --id from-shot --name "From Shot" \
  --image design.png
mdreports templates delete my-layout
```

`--templates-dir` overrides the user templates directory on any command.

---

# HTTP API — developers

# HTTP API — Developers

**Audience:** Engineers running or calling `@x12i/mdreports-api`.

---

## 1. Run

```bash
npm install -g @x12i/mdreports-api
npx playwright install chromium
mdreports-api
```

Optional env:

| Variable | Purpose |
| --- | --- |
| `MDREPORTS_API_PORT` / `PORT` | Listen port (default **6460**) |
| `MDREPORTS_API_KEY` | If set, require `Authorization: Bearer <key>` (except `/health`) |
| `MDREPORTS_TEMPLATES_DIR` | User templates directory |

---

## 2. Call with curl

```bash
curl -s http://localhost:6460/health

curl -s http://localhost:6460/templates | jq .

curl -s -X POST http://localhost:6460/render/html \
  -H 'content-type: application/json' \
  -d '{"markdown":"# Hello","templateId":"clean-report"}' | jq .

curl -s -X POST http://localhost:6460/render/pdf \
  -H 'content-type: application/json' \
  -d '{"markdown":"# Hello","templateId":"clean-report"}' \
  --output report.pdf

curl -s -X POST http://localhost:6460/render/pptx \
  -H 'content-type: application/json' \
  -d '{"markdown":"# Hello\n\nSlide body","templateId":"clean-report"}' \
  --output report.pptx
```

---

## 3. Typed client

```bash
npm install @x12i/mdreports-api-client
```

```ts
import { ApiClient } from "@x12i/mdreports-api-client";

const client = new ApiClient({
  baseUrl: "http://localhost:6460",
  apiKey: process.env.MDREPORTS_API_KEY
});

const pdf = await client.renderPdf("# Hello", "clean-report");
const templates = await client.listTemplates();
```

---

## 4. Route summary

| Method | Path | Description |
| --- | --- |
| `GET` | `/health` | Liveness (no auth) |
| `GET` | `/templates` | List templates |
| `GET` | `/templates/:id` | Get template |
| `POST` | `/templates/from-html` | Create from HTML + CSS |
| `POST` | `/templates/from-image` | Create from image (multipart) |
| `PATCH` | `/templates/:id` | Update user template |
| `DELETE` | `/templates/:id` | Delete user template |
| `POST` | `/render/html` | Markdown → HTML JSON |
| `POST` | `/render/pdf` | Markdown → PDF bytes |
| `POST` | `/render/docx` | Markdown → DOCX bytes |
| `POST` | `/render/pptx` | Markdown → PPTX bytes |

---

# MCP — developers

# MCP — Developers

**Audience:** Engineers wiring agents to Markdown Reports Studio.

---

## 1. Run configure

```bash
npm install -g @x12i/mdreports-mcp-server
npx playwright install chromium
```

Example MCP client config:

```json
{
  "mcpServers": {
    "mdreports": {
      "command": "npx",
      "args": ["-y", "@x12i/mdreports-mcp-server"],
      "env": {
        "ANTHROPIC_API_KEY": "optional"
      }
    }
  }
}
```

Optional: `MDREPORTS_TEMPLATES_DIR` for the user template store.

---

## 2. Tools

- `list_templates` / `get_template`
- `render_markdown_to_html` (returns HTML inline)
- `render_markdown_to_pdf` / `render_markdown_to_docx` / `render_markdown_to_pptx` (write a file; optional `outPath`)
- `create_template_from_html` / `create_template_from_image` / `delete_template`

PPTX is always landscape 16:9; each `#` heading starts a new slide.

---

# Templates — developers

# Templates — Developers

**Audience:** Engineers integrating template stores and manifests.  
**Twin:** [Builders version](../builders/BOOK.md)

---

## 1. Built-ins

Shipped in `@x12i/mdreports-templates` (read-only):

| Id | Use |
| --- | --- |
| `clean-report` | General multi-section reports |
| `letter` | Letters / short correspondence |
| `technical-doc` | Technical documentation |

---

## 2. Layout contract

Every template directory needs:

1. `template.json` — manifest (validated by `TemplateManifestSchema`)
2. `layout.html` — must include `</head>` and slot tokens
3. `styles.css` — injected before `</head>`

Common HTML slots:

- `<!--CONTENT-->` — rendered Markdown body (required)
- `<!--TITLE-->` — document title
- additional `metaSlots` declared in the manifest

---

## 3. User templates

Writable location (never overwrites built-ins):

- default: `~/.mdreports/templates`
- override: `MDREPORTS_TEMPLATES_DIR`, SDK `templatesDir`, or CLI `--templates-dir`

Create via CLI, SDK `TemplateStore#createFromHtml` / `createTemplateFromImage`, API, MCP, or Studio.

`create-from-image` needs `ANTHROPIC_API_KEY`.

---

## 4. Images in Markdown

- HTML/PDF: absolute `http(s)` URLs or data URIs
- DOCX / PPTX: local paths and URLs are best-effort; failures become placeholders

---

## 5. PPTX

Every manifest includes a `pptx` block. Built-ins and new templates default to **landscape 16:9** (13.333″ × 7.5″).

- Each `#` (H1) starts a new slide
- Optional title slide when a document title is present (frontmatter / first heading)

---

# Templates — builders

# Templates — Builders

**Audience:** Authors designing layouts in Studio or from HTML/CSS.  
**Twin:** [Developers version](../developers/BOOK.md)

---

## 1. Built-ins

Start here before inventing a new layout:

| Id | Best for |
| --- | --- |
| `clean-report` | Multi-section reports |
| `letter` | Short correspondence |
| `technical-doc` | Technical documentation |

---

## 2. Layout contract

A template folder is three files:

| File | Role |
| --- | --- |
| `template.json` | Id, name, page/theme/DOCX/PPTX styles, meta slots |
| `layout.html` | Shell with `</head>` and `<!--CONTENT-->` |
| `styles.css` | Look-and-feel injected into the shell |

Keep slot names stable; renderers fill them from Markdown and frontmatter.

---

## 3. User templates

Your custom templates live under `~/.mdreports/templates` (or a path your team sets). Built-ins are never overwritten.

Create from:

- Studio UI (HTML or design screenshot)
- CLI `create-from-html` / `create-from-image`
- Asking an agent via MCP when configured

Screenshot drafts need an Anthropic API key.

---

## 4. Images in Markdown

Prefer absolute HTTPS image URLs in source Markdown so HTML and PDF previews stay reliable.

---

## 5. PPTX

Slides are landscape 16:9. Structure decks with `#` headings — one H1 per slide. Put deck title in YAML frontmatter `title` for an opening title slide.