markpdfdown - Moses Yebei

Abstract

A high-quality PDF to Markdown tool based on large language model visual recognition. 一款基于大模型视觉识别的高质量PDF转Markdown工具

The Problem

Converting PDFs to editable Markdown is usually lossy: tables break, formulas become images, and layout is discarded. Most tools use rule-based extraction that fails on complex documents. MarkPDFDown instead sends rendered PDF pages to a multimodal LLM and asks it to transcribe what it sees, which preserves structure at the cost of an API call per page.

What This Does

The package converts PDFs and images to Markdown using OpenAI or OpenRouter models through LiteLLM. Core logic lives in src/markpdfdown/core/: file_worker.py renders PDF pages to images, llm_client.py wraps the API call, and utils.py handles Markdown cleanup and input validation. The CLI in src/markpdfdown/cli.py supports both file arguments and stdin piping.

Configuration is environment-variable driven via src/markpdfdown/config.py — model name, temperature, max tokens, retry count. A .env.sample file documents the expected keys.

How It Is Wired

Execution starts at main in src/markpdfdown/cli.py:98, which parses arguments, validates them, then dispatches to convert_from_file or convert_from_stdin in src/markpdfdown/main.py. Those call convert_to_markdown, which uses FileWorker to render pages to images, then LLMClient.completion to get the transcription. The shortest path to an external effect is main -> convert_from_file -> convert_to_markdown -> os.makedirs — two hops from entry to filesystem write.

LLMClient is the hub: called from 14 places. create_parser, detect_file_type, and validate_page_range are each called from 10+ places, so changes to their signatures break a wide surface. The import graph is acyclic with 12 edges across 17 modules — no circular dependencies, which keeps refactoring straightforward.

The module graph shows core/utils.py as a stable leaf (3 callers, 0 dependencies) and core/llm_client.py similarly stable. main.py sits in the middle with instability 0.67, meaning it both depends on and is depended on — the natural place to add features like new output formats.

How To Use It

# Install with uv (recommended, uv.lock is present)
uv sync
uv pip install -e .

# Or with pip
pip install -e .

# Configure
cp .env.sample .env
# Edit .env: MODEL_NAME, OPENAI_API_KEY (or OPENROUTER_API_KEY)

# Convert a PDF
markpdfdown --input document.pdf --output output.md

# Convert specific pages
markpdfdown --input document.pdf --output output.md --start 1 --end 10

# Pipe mode
markpdfdown < document.pdf > output.md

A Dockerfile is present for containerized use.

Real-World Use

Batch-converting a document archive: loop over PDFs, call markpdfdown per file, store the Markdown in a content repository. The pipe mode makes this scriptable without temp files: cat report.pdf | markpdfdown > report.md. Page-range selection lets you handle large documents in chunks to stay within context windows.

Code Health & Issues

Static analysis found 8 issues (0 critical, 2 high, 5 medium, 1 low):

High - Third-party GitHub Actions pinned to tags, not commit SHAs — .github/workflows — a moved tag can run arbitrary code with your CI secrets
High - CI has 16 test files but no workflow runs them — .github/workflows — the green check proves nothing
Medium - No permissions block on workflows that reference secrets — .github/workflows/changelog.yml
Medium - No Dependabot/Renovate configured — dependencies go unpatchable
Medium - Docker base image python:3.9-slim not pinned by digest — Dockerfile
Medium - No dependency vulnerability scan in CI — .github/workflows
Medium - No non-root USER in the Dockerfile — container runs as root
Low - No timeout-minutes on workflow jobs — a wedged run blocks the queue

One code-quality finding: src/markpdfdown/core/llm_client.py has nesting depth of 6 — extract guard clauses to flatten.

A uv.lock file is present, so builds are reproducible despite no lockfile warning in the analysis.

The Bottom Line

A clean, small codebase (17 Python files) with a sensible architecture and actual tests — though CI doesn't run them. The LLM-based approach is genuinely better than rule-based PDF extraction for complex documents. The main risks are supply-chain: unpinned CI actions and base image. Suitable for anyone needing high-fidelity PDF-to-Markdown conversion and willing to pay API costs per page.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

45 files

Python17
Markdown10
YAML4
TOML1

Docker

Module dependencies

The 10 most depended-upon modules of 17, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_markpdfdown_core_utils["utils"] n1_src_markpdfdown_main["main"] n2_markpdfdown_core_file_worker["file_worker"] n3__markpdfdown_core_llm_client["llm_client"] n4_src_markpdfdown_cli["cli"] n5_src_markpdfdown___init__["__init__"] n6_src_markpdfdown_config["config"] n7_rc_markpdfdown_core___init__["__init__"] n8_src_markpdfdown___main__["__main__"] n9_tests___init__["__init__"] n5_src_markpdfdown___init__ --> n1_src_markpdfdown_main n8_src_markpdfdown___main__ --> n4_src_markpdfdown_cli n4_src_markpdfdown_cli --> n5_src_markpdfdown___init__ n4_src_markpdfdown_cli --> n1_src_markpdfdown_main n7_rc_markpdfdown_core___init__ --> n2_markpdfdown_core_file_worker n7_rc_markpdfdown_core___init__ --> n3__markpdfdown_core_llm_client n7_rc_markpdfdown_core___init__ --> n0_src_markpdfdown_core_utils n2_markpdfdown_core_file_worker --> n0_src_markpdfdown_core_utils n1_src_markpdfdown_main --> n6_src_markpdfdown_config n1_src_markpdfdown_main --> n2_markpdfdown_core_file_worker n1_src_markpdfdown_main --> n3__markpdfdown_core_llm_client n1_src_markpdfdown_main --> n0_src_markpdfdown_core_utils

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh7 occurrences

.github/workflows

requarks/changelog-action@v1, ncipollo/release-action@v1.12.0, stefanzweifel/git-auto-commit-action@v4, docker/setup-qemu-action@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Make CI invoke the test suite it hashigh16 occurrences

.github/workflows

16 test files, no test command in any workflow

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/changelog.yml

3 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

Dockerfile

python:3.9-slim, python:3.9-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/changelog.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.