PDF Split & Convert

Convert a PDF file to readable markdown text. Handles large PDFs efficiently.

Input

• $ARGUMENTS[0], Path to the PDF file (required)

Choose the method first

Before reading anything, check whether pdftotext (part of poppler) is available:

which pdftotext

• If available → use the pdftotext path below. It is 10, 100× faster than the Read tool, uses no model context for the text content, and doesn't suffer from stream idle timeouts. Always prefer this for PDFs longer than ~30 pages.
• If not available → fall back to the Read-tool path. Warn the user that large PDFs (>40 pages) may hit stream idle timeouts when run in subagents (~12 min cap). Prefer running in the main conversation for large files.

Resolve the path and get page count

1. If the path is relative, resolve it relative to the current working directory.
2. Run mdls -name kMDItemNumberOfPages "<pdf_path>" to get the total page count. If mdls is unavailable or returns (null), use pdftotext or Read to probe.

Method A, pdftotext (preferred)

Extract the full PDF to text in one shot, then trim at references/appendix and add page markers. pdftotext emits a form-feed character (\f) at every page break, use that for pagination.

Reference implementation (bash + awk):

PDF="$1"
OUT="${PDF%.pdf}.md"
TITLE=$(basename "${PDF%.pdf}")
TMPTXT=$(mktemp)

pdftotext -layout "$PDF" "$TMPTXT"

awk -v title="$TITLE" '
BEGIN {
    print "# " title
    print ""
    page = 1
    printf "---\n## Pages %d-%d\n---\n", page, page+19
    next_marker = page + 20
}
{
    # Convert form-feed page breaks to newlines and count pages
    n = gsub(/\f/, "\n")
    if (n > 0) {
        page += n
        if (page >= next_marker) {
            printf "\n---\n## Pages %d-%d\n---\n", next_marker, next_marker+19
            next_marker += 20
        }
    }