PDF to Markdown

---
name: pdf-to-markdown
description: Convert PDFs and Office documents (Word .docx, PowerPoint .pptx, Excel .xlsx) into clean Markdown using Microsoft's markitdown. Use this skill whenever the user wants to turn a document into Markdown or plain text — e.g. "convert this PDF to markdown", "extract the text from this docx", "turn these slides into markdown for my notes", "get the tables out of this spreadsheet as markdown", or references a .pdf/.docx/.pptx/.xlsx file they want as text/markdown. Trigger even when the user doesn't say "markdown" explicitly but clearly wants a document's contents as editable text. This skill targets TEXT-BASED documents (PDFs with a real text layer); it does not run OCR on scanned/image-only PDFs.
---

# PDF to Markdown

Convert PDFs and common Office documents into clean, readable Markdown using [Microsoft markitdown](https://github.com/microsoft/markitdown). markitdown preserves structure that matters for downstream use — headings, lists, and (critically) tables — which naive text extraction loses.

## When to use this

Use for text-based documents where the goal is editable Markdown or plain text:

- **PDF** (`.pdf`) — with a real text layer (not scanned images)
- **Word** (`.docx`)
- **PowerPoint** (`.pptx`) — slide text and notes
- **Excel** (`.xlsx`) — sheets rendered as Markdown tables

If the PDF is a scan (image-only), markitdown returns little or no text. Detect this (see Troubleshooting) and tell the user rather than returning an empty file — this skill deliberately does not do OCR.

## Prerequisite: markitdown must be installed

Check first, install if missing:

```bash
markitdown --help >/dev/null 2>&1 || pip install "markitdown[pdf,docx,pptx,xlsx]"
```

If `pip` is externally managed (common on newer macOS/Linux), add `--break-system-packages`, or install into a virtualenv.

## Workflow

1. **Confirm the input file(s)** exist and are a supported type.
2. **Run the conversion** using the bundled script (handles single files, multiple files, and whole directories):

   ```bash
   python scripts/convert.py <input_path> [more_paths...] [-o OUTPUT_DIR]
   ```

   The script writes one `.md` file per input, next to the source (or into `OUTPUT_DIR` if given), and prints where each was written.

3. **Sanity-check the output.** Open the resulting `.md`. Confirm headings and tables look right and the file isn't suspiciously empty.
4. **Report** the output path(s) to the user. If any file produced empty/near-empty output, flag it as a likely scanned PDF (see Troubleshooting).

For a quick one-off you can skip the script and pipe directly:

```bash
markitdown input.pdf > output.md
```

But prefer `scripts/convert.py` for batches, directories, and the empty-output check.

## Bundled script

`scripts/convert.py` — converts one or more files (or a directory) to Markdown. Flags: `-o/--output-dir` to redirect output, `--stdout` to print instead of writing files. It skips unsupported extensions with a warning and flags empty results.

## Troubleshooting

- **Empty or tiny output from a PDF** → the PDF is almost certainly scanned/image-only. This skill does not OCR. Tell the user, and suggest an OCR tool (e.g. `ocrmypdf input.pdf output.pdf` first, then re-run) if they need it.
- **`No module named 'pdfminer'` / missing extractor** → the format extra wasn't installed. Re-run `pip install "markitdown[pdf,docx,pptx,xlsx]"`.
- **Garbled tables in PDF** → PDF table extraction is inherently lossy; docx/xlsx tables are far more reliable. Note the limitation to the user.
- **`onnxruntime` cpuid warning** on stderr → harmless, ignore it.