# Pdf To Markdown

> Convert a PDF (especially academic papers) to clean Markdown using MinerU — preserves reading order, LaTeX equations, tables, and figures, and runs on the GPU. Use when the user asks to convert/extract a PDF to markdown/text. Invoke directly — no need for the user to type the skill name.

- **Type:** Skill
- **Install:** `agentstack add skill-yhbcode000-paper-share-skills-pdf-to-markdown`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yhbcode000](https://agentstack.voostack.com/s/yhbcode000)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [yhbcode000](https://github.com/yhbcode000)
- **Source:** https://github.com/yhbcode000/paper-share-skills/tree/main/pdf-to-markdown
- **Website:** https://blog.yhbcode000.tech/paper-share-skills/

## Install

```sh
agentstack add skill-yhbcode000-paper-share-skills-pdf-to-markdown
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PDF → Markdown (MinerU)

Converts PDFs to clean, structure-preserving Markdown using **MinerU**
(`opendatalab/MinerU`), the highest-fidelity open-source engine for academic
papers. Runs the **pipeline backend on the GPU** (CUDA). Output keeps
heading hierarchy, inline LaTeX math (`$...$`), figures, and tables (as HTML).

## When to use

- The user asks to "convert / extract / turn this PDF into markdown (or text)."
- Best fit: **academic papers** — multi-column layouts, LaTeX math, tables, references.
- Also handles images, `.docx`, `.pptx`, `.xlsx` (pass the file directly).

## How to run

MinerU lives in a dedicated isolated env and is driven through the bundled
`convert.py` wrapper, which calls MinerU's Python API **in-process**.

> Do **not** use the `mineru` CLI here — in 3.4.0 it spins up a local API server
> that returns `502 Bad Gateway` on Windows. The wrapper bypasses that.

```
"$MINERU_PYTHON" \
  "/pdf-to-markdown/convert.py" \
  "" "" --lang en

- Arg 1 — input file (pdf/image/docx/pptx/xlsx).
- Arg 2 — output directory.
- `--lang` — OCR language hint: `en` for English, `ch` for Chinese/mixed (default `ch`,
  which also handles English). Only affects OCR'd (scanned) pages.
- The script prints `DONE -> ` on success.

### Output layout

```
//auto/.md       # the markdown
//auto/images/          # extracted figures (referenced from the md)
//auto/_*.json    # layout/content metadata (can be ignored)
```

## After converting

1. Read the printed `DONE -> ...md` path and report it to the user.
2. Optionally show a short preview (title + first headings).
3. Note where extracted images were written.
4. Quality is normally high: headings as `#`, inline math as `$...$`, tables as
   `` HTML (with LaTeX inside cells). If a scanned PDF comes out garbled,
   re-run with `--method ocr`.

## Preflight / setup (only if something is missing)

- Interpreter with MinerU (env `MINERU_PYTHON`, default `python`).
- Verify CUDA: `$MINERU_PYTHON -c "import torch; print(torch.cuda.is_available())"` → `True`.
- Models are pre-downloaded to `~/.cache/huggingface/hub/` (one-time).

If the env is missing, recreate it (install `uv` first if needed):
```
uv venv --python 3.12 ""
uv pip install --python "/Scripts/python.exe" torch torchvision --index-url https://download.pytorch.org/whl/cu124
uv pip install --python "/Scripts/python.exe" -U "mineru[core]"
"/Scripts/mineru-models-download.exe" -s huggingface -m pipeline
```
Then set `MINERU_PYTHON` to `/Scripts/python.exe` (Windows) or
`/bin/python` (macOS/Linux). On macOS/Linux the models-download binary is
`mineru-models-download` (no `.exe` suffix).

## Troubleshooting
- **`cuda.is_available()` is False** → reinstall torch from the `cu124` index (see setup).
  The pipeline still runs on CPU if needed, just slower.
- **Model download fails / slow** → re-run `mineru-models-download` with `-s modelscope`.
- **Scanned PDF garbled** → add `--method ocr` to the `convert.py` call.
- **`vlm-engine` / `hybrid-engine` backends** → these need vLLM/SGLang (Linux); they 502
  on Windows. Stick with the default `pipeline` backend used by the wrapper.

## Lightweight fallback (simple / Office docs)

For non-paper files where layout fidelity doesn't matter, Microsoft's **MarkItDown**
is faster and simpler — but it mangles academic two-column PDFs and tables, so prefer
MinerU for papers:
```
"$MINERU_PYTHON" -m pip install markitdown
"$MINERU_PYTHON" -m markitdown "" > out.md
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yhbcode000](https://github.com/yhbcode000)
- **Source:** [yhbcode000/paper-share-skills](https://github.com/yhbcode000/paper-share-skills)
- **License:** Apache-2.0
- **Homepage:** https://blog.yhbcode000.tech/paper-share-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yhbcode000-paper-share-skills-pdf-to-markdown
- Seller: https://agentstack.voostack.com/s/yhbcode000
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.