markpdf

name	markpdf
description	Convert Markdown to premium-themed PDFs, slide decks (PPTX/PDF), styled HTML, and shareable links via the MarkPDF MCP server. Use when raw Markdown isn't enough — reports, pitches, academic papers, résumés, decks, printable docs.

MarkPDF Skill

MarkPDF turns Markdown into production-grade PDFs, decks, and HTML through a hosted MCP server. This skill teaches Claude:

1. The default opinionated workflow (what to do when the user just says "make a PDF")
2. The decision tree for variations (custom theme, sharing, password, email gate, etc.)
3. The OS-aware delivery step (auto-open the result when possible)

Read references/workflows.md for the full playbook with copy-paste recipes. This file is the index + golden rules.

When to use this skill

Trigger on requests like:

• "Make this a PDF / printable / executive report / brochure"
• "Turn this into slides / a pitch deck / a PowerPoint / a Marp deck"
• "Style this as a Notion-like doc / academic paper / corporate report"
• "Share this document with a link" / "Send to alice@…"
• "Apply theme X to this Markdown"

Do not use this skill for:

• Plain in-chat Markdown rendering (no export needed)
• PDFs of arbitrary HTML/CSS unrelated to Markdown
• Editing existing PDFs (MarkPDF only generates)

The 7 MCP tools

Tool	Use it when	Quota
whoami	Always call first if unsure of tier/quota	Free
list_themes	User asks "what themes are available?" or you need to verify a slug	Free
redeem_license	User has a Pro license key and wants to upgrade in-place	Free
convert_markdown_to_html	Iterating on styling, embedding, previewing	Free
convert_markdown_to_pdf	Final document export	Yes
convert_markdown_to_slides	Slide deck (PDF or PPTX) — Marp-compatible	Yes
create_share_link	Default delivery channel — clean URL, optional gating	Free

---

🎯 The default workflow (do this unless told otherwise)

When a user gives you Markdown content and asks for any kind of styled output:

┌─ 1. Detect intent (PDF | slides | HTML)  ──────────────────┐
│                                                              │
│  2. Pick a theme (intent → theme map, see below)             │
│                                                              │
│  3. whoami (skip if already done this session)               │
│                                                              │
│  4. If user has a Pro license key in context AND they're     │
│     on free tier → propose redeem_license (don't force)      │
│                                                              │
│  5. Generate the artifact:                                   │
│     - PDF      → convert_markdown_to_pdf                     │
│     - Slides   → convert_markdown_to_slides                  │
│     - HTML     → convert_markdown_to_html                    │
│                                                              │
│  6. Create a share link (always, in parallel)                │
│     → create_share_link returns markpdf.app/d/<id>           │
│                                                              │
│  7. Deliver to the user:                                     │
│     a) Show the SHARE link prominently (markpdf.app/d/…)     │
│     b) Show the download link as a secondary option          │
│     c) Auto-open the share link in the browser if possible   │
│        (see "OS-aware open" below)                           │
│                                                              │
│  8. Report quota status if free tier (X/2 today, 00:00 UTC)  │
└──────────────────────────────────────────────────────────────┘

Why share link first? Brand-consistent (markpdf.app/d/abc), revocable, trackable, doesn't leak bucket internals. The raw R2 download URL is 600+ chars and exposes infra details — only surface it if the user explicitly wants the file.

🌐 OS-aware "auto-open" step

If you have shell/bash access, after delivering the URL, run the right open command for the user's OS:

# macOS (Darwin)
open "https://markpdf.app/d/abc123"

# Linux
xdg-open "https://markpdf.app/d/abc123"

# Windows (PowerShell)
Start-Process "https://markpdf.app/d/abc123"

# Windows (cmd)
start "" "https://markpdf.app/d/abc123"

# WSL
wslview "https://markpdf.app/d/abc123"   # or: cmd.exe /c start "https://…"

Detect the OS with uname -s, env var OSTYPE, or process.platform. If detection fails or you can't run shell commands, just present the URL prominently — don't error out.

Skip auto-open when:

• The user is in a non-interactive context (CI, scripted environment)
• The user explicitly said "just give me the link"
• You're in a chat-only environment with no shell

Golden rules

1. Default to the share link as the deliverable. The raw R2 download URL is a fallback for power users only.
2. Call whoami once per session before the first export. Free tier = 2 exports/day (resets at 00:00 UTC), themes slate, paper, ivory only.
3. Iterate styling with convert_markdown_to_html, not _to_pdf. HTML calls are free; PDF calls eat quota.
4. Pick the theme deliberately (see references/themes.md). Wrong theme = wasted export. Default to slate.
5. Front-load metadata in YAML frontmatter (title, author, date). All themes use it. See references/frontmatter.md.
6. Slides use Marp syntax — --- separates slides. See references/slides.md.
7. Pro-only features fail loudly on a free token. Check whoami before promising custom fonts or Pro themes.
8. Honor explicit user requests — if they say "no need to share, just download", skip step 6/7. If they say "send to [e-mail]", use accessEmails.

---

Variation playbook (overrides to the default flow)

The full recipes are in references/workflows.md. Quick map:

User says…	Override default with…
"share with [e-mail]"	create_share_link + accessEmails: ["[e-mail]"]
"password-protect it: hunter2"	create_share_link + password: "hunter2"
"make it permanent / no expiry"	Requires Pro tier; warn if free
"use my brand color #ff5722"	customizations.accent: "#ff5722"
"make it look like McKinsey"	theme consul (Pro) — fall back to paper if free
"use the Inter font"	customizations.fontBody: "Inter" (Pro only)
"PowerPoint format"	convert_markdown_to_slides with format: "pptx"
"16:9 deck" / "4:3 deck"	ratio arg on slides
"letterhead with our logo"	pageOptions.headerTemplate (Pro) — see references/customization.md
"academic paper"	theme scholar or academic (Pro)
"I have a license key MPDF-xxx"	Call redeem_license to upgrade in-place
"just give me the file / download link"	Skip share link; surface raw download URL
"preview it / show me what it'd look like"	convert_markdown_to_html (free, no quota)

Intent → theme cheat sheet (PDFs)

Intent	Free	Best Pro
Internal doc, dev notes	slate	slate
Editorial / longform	paper	prose, folio
Minimalist / Japanese	ivory	ivory
Corporate / consulting	paper (fallback)	consul
Pitch / startup	paper (fallback)	aurora
Academic	paper (fallback)	scholar, academic
Dark mode	— (no free dark)	midnight, hertz, obsidian, rosepine
Luxury / premium	—	obsidian
Creative / handwritten	—	quill
Newsletter	—	prose

Full catalog: references/themes.md.

---

Failure modes — handle gracefully

Symptom	Meaning	What to do
quota_exceeded	Free tier used up today's 2 exports	Show reset time (whoami.dailyResetAt — next 00:00 UTC) + upgrade URL. Offer redeem_license if they have a key.
theme_locked	Pro theme requested with free token	Suggest closest free theme + mention upgrade
unknown_theme (auto-fallback)	Typo in slug	Server falls back to slate and returns themeFallback.didYouMean. Surface the suggestion.
markdown_too_large	>2 MB body (1 MB for slides)	Split or strip embedded base64 images
overrideCSS rejected	Bad @import host	Only fonts.googleapis.com, fonts.gstatic.com, assetBaseUrl host allowed
Bash open command fails	Headless env / no DISPLAY	Just present the URL — don't loop trying

Authentication (only mention when user asks)

• Trial token (no signup): POST https://markpdf.app/api/mcp/trial-token
• Pro token from license: in-chat with redeem_license, or POST /api/mcp/exchange, or web at /account/mcp
• Setup snippets: https://markpdf.app/integrations/mcp

Reference files (load only when needed)

• references/workflows.md ← READ THIS FIRST for full recipe playbook
• references/themes.md — full catalog, intent mapping
• references/slides.md — Marp syntax, layouts
• references/customization.md — accent, fonts, overrideCSS, pageOptions
• references/frontmatter.md — YAML metadata
• examples/report.md — Executive board memo (consul)
• examples/pitch-deck.md — Series A pitch (aurora slides)
• examples/academic.md — Research paper (scholar/academic)
• scripts/render.sh — curl fallback when MCP isn't installed
• scripts/open-url.sh — OS-aware URL opener