pdf2md

PDF → Markdown & Editable Figures

One tool. Uses pdf_to_markdown with your local PDF. Core Markdown conversion needs no cloud API. Editable figure reconstruction uses the built-in autofigure pipeline when vlm_provider + fal_api_key are configured; otherwise degrades gracefully to a layered-SVG fallback.

When to use

Trigger words / phrases (Chinese or English):

Paper PDF to Markdown / PDF to md
Convert this paper to Markdown
Extract paper images / Export paper figures
Export editable figures / Editable SVG / Editable drawio
pdf to markdown / parse paper PDF / extract paper figures
Parse PDF into structured text

Tool

pdf_to_markdown(
    pdf_path = "<path to PDF>",
    ...options...
)

Parameters

Parameter	Type	Default	Notes
`pdf_path`	string	required	Absolute or workspace-relative path to the PDF
`out_root`	string	`outputs/pdf2md`	Root output dir; paper lands in `<out_root>/<original_pdf_stem>/`
`backend`	`"docling"` \| `"mineru"`	`"docling"`	Markdown engine; mineru requires separate CLI install
`export_figures`	bool	`true`	Extract labelled figures to `assets/figures/`
`figure_box_source`	`"auto"` \| `"docling"` \| `"fitz"`	`"auto"`	How figure boxes are located
`export_svg`	bool	`true`	Attempt SVG per figure (mutool → pdf2svg → fitz → PNG wrapper)
`export_drawio`	bool	`true`	Attempt drawio per figure (built-in editable conversion from SVG)
`enable_rebuild`	bool	`true`	Run editable reconstruction (see below). DEFAULT IS TRUE.

enable_rebuild defaults to true. When the autofigure pipeline is fully configured (needs fal_api_key in config + a VLM provider), it runs SAM3 segmentation → RMBG-2.0 background removal → VLM SVG template → icon replacement. When not configured it falls back to a two-layer SVG that embeds the raster PNG with an empty vector overlay. The fallback never crashes the pipeline.

Editable rebuild pipeline

The autofigure pipeline runs entirely in-process (no external CLI needed):

Step	Module	What it does
1	`SegmentFigureTool`	SAM3 via fal.ai — detects icons/elements
2	`CropRemoveBgTool`	RMBG-2.0 (local torch) — removes backgrounds
3	`GenerateSVGTemplateTool`	VLM reconstructs figure layout as SVG
4	`ReplaceIconsSVGTool`	Embeds transparent icon PNGs into SVG

Requirements for full autofigure rebuild:

fal_api_key set in ~/.clawphd/config.json under tools.autofigure
A multimodal VLM provider configured (openrouter / gemini recommended)
pip install clawphd-ai[autofigure] (torch / torchvision / transformers)

Output directory layout

outputs/pdf2md/<original_pdf_stem>/
    <original_pdf_name>.pdf   ← copy of source PDF
    <original_pdf_stem>.md    ← full Markdown of the paper
    meta/
        doc.json             ← docling structured document model
        run.json             ← run metadata: timing, tool detection, warnings
        figures.json         ← array of per-figure metadata records
    assets/
        figures/
            fig_001/
                fig_001.png          ← cropped raster (always present if PyMuPDF available)
                fig_001.svg          ← vector SVG (only when enable_rebuild=false)
                fig_001.drawio       ← drawio XML (only when enable_rebuild=false)
                meta.json            ← figure-level metadata
                rebuild/             ← present when enable_rebuild=true
                    autofigure/      ← autofigure intermediate files (SAM3, crops, icons)
                    rebuilt.svg      ← primary SVG output (autofigure or layered-SVG fallback)
                    rebuilt.drawio   ← primary drawio output
            fig_002/
            ...

paper_id (sha1(pdf_bytes)[:12]) is returned in metadata for traceability.

SVG export priority

mutool draw — highest-quality vector SVG, full-page then viewBox-cropped
pdf2svg — alternative CLI, full-page then viewBox-cropped
fitz (PyMuPDF built-in) — per-figure cropbox SVG
PNG-embedding SVG — final fallback, always works

`run.json` fields

{
  "paper_id":        "...",
  "figures_total":   5,
  "svg_exported":    5,
  "drawio_exported": 5,
  "rebuilt_exported":5,
  "elapsed_sec":     12.4,
  "tools_detected": {
    "mutool":             true,
    "pdf2svg":            false,
    "svgtodrawio":        false,
    "autofigure_enabled": true
  },
  "warnings": []
}

Typical workflow

Simplest call (all defaults)

pdf_to_markdown(pdf_path="path/to/paper.pdf")

Produces <stem>.md, copied PDF, all figures as PNG + SVG, and a rebuilt.svg per figure (autofigure if configured, else layered-SVG fallback).

With drawio export

pdf_to_markdown(
    pdf_path      = "papers/attention_is_all_you_need.pdf",
    export_drawio = true
)

Disable rebuild (faster, skips reconstruction step)

pdf_to_markdown(
    pdf_path       = "paper.pdf",
    enable_rebuild = false
)

Use MinerU backend

pdf_to_markdown(
    pdf_path = "paper.pdf",
    backend  = "mineru"
)

Requires the MinerU CLI (mineru or magic-pdf) on PATH. Falls back to docling automatically if MinerU is absent or fails.

Return value (JSON string)

{
  "paper_id":         "<12-char sha1>",
  "out_dir":          "outputs/pdf2md/<original_pdf_stem>",
  "md_path":          "outputs/pdf2md/<original_pdf_stem>/<original_pdf_stem>.md",
  "source_pdf_copy":  "outputs/pdf2md/<original_pdf_stem>/<original_pdf_name>.pdf",
  "figures_total":    5,
  "svg_exported":     5,
  "drawio_exported":  5,
  "rebuilt_exported": 5,
  "backend_used":     "docling",
  "elapsed_sec":      12.4,
  "warnings":         []
}

Report the out_dir and md_path to the user so they know where to find the outputs. If warnings is non-empty, summarise them briefly.

Example conversation

User: 帮我把 /home/me/papers/resnet.pdf 转成 Markdown，并导出所有图的可编辑 SVG

Step 1: pdf_to_markdown(pdf_path="/home/me/papers/resnet.pdf", export_svg=true)

Step 2: 回复用户（中文）：
  - Markdown 已保存到 outputs/pdf2md/<original_pdf_stem>/<original_pdf_stem>.md
  - 共检测到 N 张图，已导出为 PNG + SVG
  - 每张图的可编辑重建结果在 rebuild/rebuilt.svg
  - 若需要 drawio 格式，可再次调用并加上 export_drawio=true