marker-convert

Category: Docs & Knowledge | Uploader: RebeccaStevenson | Downloads: 0 | Version: v1.0（Latest）

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.

Changelog: Source: GitHub https://github.com/RebeccaStevenson/skills_rebecca

Directory Structure

Current level: tree/main/marker-convert/

📁 agents/
- 📄 openai.yaml 238 B
📁 config/
- 📄 marker_convert.env 723 B
📁 references/
- 📄 marker-cli.md 4.1 KB
📁 scripts/
- 📄 marker_convert.sh 20.4 KB
- 📄 smoke_test.sh 3.5 KB
📄 SKILL.md 4.7 KB

SKILL.md

---
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](https://github.com/datalab-to/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.

```bash
# 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
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

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

marker-convert

Directory Structure

SKILL.md

Report

Notice