marker-convert

name	marker-convert
description	Convert PDFs to markdown, JSON, or HTML using the Marker CLI. Use when the user wants to convert PDF content into text-based formats (markdown, HTML, JSON), mentions "marker" or "marker_single", or asks to batch-convert a folder of PDFs into readable text. Handles single-file and batch-folder conversion, resuming interrupted runs, LLM-enhanced output, and conversion state/error log review.

Marker Convert

Convert PDFs into markdown, extracted images, JSON, and HTML via the Marker CLI.

Workflow

1. Confirm marker_single is available on PATH.
2. Run the wrapper script (it always processes one PDF at a time, sequentially).
3. For folder inputs, monitor progress and state logs under <output>/state.
4. Verify outputs: content files (.md, .json, .html) and extracted images in each document's subdirectory.

Output Structure

Marker creates a subdirectory per input PDF, named after the PDF stem. Each subdirectory contains the converted content file and a metadata JSON:

<output>/
├── paper1/
│   ├── paper1.md            # (or .json / .html depending on --format)
│   ├── paper1_meta.json     # conversion metadata
│   └── images/              # extracted figures (JPEGs)
│       ├── paper1_0_0.jpeg
│       └── ...
├── paper2/
│   ├── paper2.md
│   ├── paper2_meta.json
│   └── images/
└── state/                   # wrapper state/log directory
    ├── processed_files.txt  # absolute paths of successfully converted PDFs
    ├── conversion_log.txt   # timestamped session log with per-file outcomes
    ├── failed_conversions.txt
    ├── failed_conversions_archive.txt
    └── error_details.txt    # stderr captured from failed conversions

Image extraction can be disabled with --disable-image-extraction.

Quick Start

Resolve script paths relative to this skill's directory. In Claude Code, ${CLAUDE_SKILL_DIR} is automatically replaced with the absolute path to this skill. In other agents (Codex, etc.), resolve the skill directory from the skill catalog or installation path.

# Single PDF -> markdown + images
bash "${CLAUDE_SKILL_DIR}/scripts/marker_convert.sh" \
  --input /path/to/paper.pdf \
  --output /path/to/output \
  --format markdown

# Folder of PDFs -> sequential markdown conversion (one PDF at a time)
bash "${CLAUDE_SKILL_DIR}/scripts/marker_convert.sh" \
  --input /path/to/pdf_folder \
  --output /path/to/output \
  --format markdown

State files are written to <output>/state by default (processed_files.txt, conversion_log.txt, failed_conversions.txt, error_details.txt), so re-runs skip already processed PDFs unless --force is set.

Why use the wrapper instead of raw Marker?

Marker natively supports --skip_existing, which skips PDFs whose output subdirectory already exists. The wrapper's processed_files.txt approach is more robust because it:

• Tracks at the file level, not the directory level — moving or renaming output folders doesn't break resume
• Separates successes from failures — failed_conversions.txt and error_details.txt let you diagnose and retry failures without guessing which PDFs had problems
• Logs everything — conversion_log.txt records timestamped per-file outcomes (SUCCESS / FAILED / SKIPPED) and session summaries, so you have an audit trail across multiple runs
• Continues on error by default — a single bad PDF won't halt a batch; the wrapper records the failure and moves on (use --fail-fast to override)

Scripts

Script	Purpose
scripts/marker_convert.sh	Primary wrapper — sequential conversion with persistent state/logging and continue-on-error
scripts/smoke_test.sh	Regression test: single conversion, resume skip behavior, continue-on-error, missing-key guard

Configuration

The wrapper auto-loads config/marker_convert.env (relative to the scripts directory). Override with --settings <path> or disable with --no-settings. CLI flags always take precedence over settings-file values.

To enable LLM-enhanced conversion, set USE_LLM=true in the settings file or pass --use-llm. The wrapper validates that the required API key is present and exits with guidance if not.

Refer to references/marker-cli.md for the full list of CLI options, config keys, and supported Marker flags.

Smoke Test

To validate the skill after edits:

bash "${CLAUDE_SKILL_DIR}/scripts/smoke_test.sh" \
  --pdf /path/to/sample.pdf

References

• references/marker-cli.md — full CLI option reference, config key documentation, output format details, and version notes