paper2md

name	paper2md
description	Agent-first local arXiv paper-to-Markdown tool. Use when given a modern arXiv ID or arXiv /abs/ or /pdf/ URL and you need a saved Markdown artifact without dumping the paper into context. Do not use for local PDFs, arbitrary PDF URLs, DOI/search tasks, web pages, markxiv.org URLs, or figure/graph understanding.

paper2md

paper2md converts one arXiv paper into one local Markdown artifact and prints a small JSON receipt. It fetches arXiv directly and runs local conversion; it is not a markxiv.org wrapper. The engine tries arXiv HTML first for cleaner citation/figure links, then falls back to source/PDF conversion.

Workflow

paper2md read 1706.03762
paper2md read https://arxiv.org/abs/1706.03762
paper2md read https://arxiv.org/pdf/1706.03762.pdf
printf '{"input":"1706.03762"}' | paper2md read -

Stdout is the machine contract: one JSON receipt. Paper content is only in artifacts.markdown.

{
  "success": true,
  "tool": "paper2md",
  "status": "ok",
  "id": "1706.03762",
  "artifacts": { "markdown": "/tmp/paper2md-.../1706.03762.md" }
}

Read the Markdown file only when the paper content is actually needed.

Use vs other tools

• arXiv ID or arXiv /abs///pdf/ URL -> paper2md.
• Local PDF or downloaded paper file -> transcribe-cli.
• General web page or arbitrary remote PDF -> web/document tool appropriate to the task.
• Search/DOI discovery -> search first, then call paper2md only after you have an arXiv ID/URL.

Caveats

• Requires pandoc and pdftotext on PATH; build requires Rust/Cargo.
• Quality depends on available arXiv HTML/source/PDF. Text structure and citation links are usually useful; complex equations and large tables may still be rough.
• No VLM, OCR-heavy workflow, image extraction, or graph/chart interpretation. Do not claim figures were understood.

Failures still return JSON on stdout; branch on error.code, not prose.