pdf-to-markdown-cli 0.5.2__tar.gz → 1.0.1__tar.gz

pdf_to_markdown_cli-1.0.1/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog
+
+<!-- markdownlint-disable MD024 -->
+
+All notable changes to `pdf-to-markdown-cli` are documented here.
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html), and this file follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [1.0.1] - 2026-09-29
+
+### Added
+
+- Multilingual sample documents in `examples/`: scanned excerpts in Russian (Tolstoy), German Fraktur (Grimm), classical Chinese with music notation (Shijing Gupu), and English (Darwin's 1859 diagram), each with its reference output.
+- An opt-in live test suite (`pytest -m live`) that converts every sample with the real API and checks text, chunk merging, page numbering, images, and HTML/JSON output. A manual **Live API tests** workflow runs it in CI.
+- `SECURITY.md`, issue and pull request templates, and `examples/README.md`.
+
+### Changed
+
+- Rewrote `README.md` (now also the PyPI page) and `CONTRIBUTING.md`.
+- Releases now publish to PyPI automatically through Trusted Publishing when a version tag is pushed.
+
+## [1.0.0] - 2026-09-29
+
+First stable release: a rewrite on Datalab's current Convert API with a scriptable, re-runnable CLI. See "Upgrading from 0.x" in the README.
+
+### Added
+
+- `--mode {fast,balanced,accurate}`, `--page-range`, `--no-image-captions`, `--skip-cache`, and `--api-option KEY=VALUE` for any other Convert API field.
+- Multiple inputs per command, e.g. `pdf-to-md a.pdf b.docx docs/`.
+- `--dry-run` previews files, pages, and chunks without calling the API or needing a key.
+- `--overwrite`: existing outputs are now skipped by default, so re-runs only convert what's new.
+- `-j/--concurrency`: chunks and files convert in parallel (default 5).
+- `--timeout`, `-q/--quiet`, `--keep-line-breaks`, and `--api-key`.
+- The `DATALAB_API_KEY` environment variable, matching Datalab's official SDK. `MARKER_PDF_KEY` still works.
+- Input types: `.xlsm`, `.xltx`, `.csv`, `.htm`, `.tif`.
+- A per-file result line and an end-of-run summary with page count and cost. Converted paths are printed to stdout.
+- Markdown paragraphs that were hard-wrapped are joined (disable with `--keep-line-breaks`).
+- Markdown no longer repeats each generated image description as a paragraph under the image. The description stays in the alt text.
+
+### Changed
+
+- Uses `POST /api/v1/convert`; the `/api/v1/marker` endpoint is deprecated upstream.
+- Deterministic output names: `report.md` + `report_images/` instead of UUID-keyed names. Same-name inputs become `a.pdf.md` / `a.docx.md`, and other clashes get a numeric suffix. Names are compared case-insensitively, and an output never overwrites an input file.
+- `-o/--output-dir` accepts relative paths and mirrors the input folder tree.
+- `--llm` now means `--mode balanced` and `--max` means `--mode accurate`. `--strip`, `--force`, and `--langs` are ignored with a warning because the API removed them. `--pages`, `--noimg`, `-cs`, and `-mp` are still accepted as aliases of the new flag names.
+- Exit codes: `0` success, `1` some files failed, `2` usage/auth error, `130` interrupted.
+- Quieter default output. Timestamps and debug logs only appear with `-v`.
+- Dependencies trimmed to `requests`, `pikepdf`, and `tqdm`.
+- Flat package layout and a pytest suite with 97% branch coverage. CI runs ruff, tests on Python 3.10-3.14, and a packaging check.
+
+### Fixed
+
+- `--html` and `--json` produced no output, because the response fields were misnamed.
+- Failures (including an invalid API key) exited `0` and printed "Conversion completed successfully".
+- `--max-pages` was applied to every chunk instead of the whole document.
+- Retries never happened because the client swallowed exceptions. 429/5xx/network errors now retry with backoff and honor `Retry-After`.
+- Long conversions were marked failed after about 5 minutes of polling.
+- A 30-second request timeout broke uploads of large files.
+- Re-running on a directory re-converted previously extracted images, and `--html` could overwrite `.html` inputs.
+- Page separators, JSON block ids, and image names restarted in every chunk. Image links broke on filenames with spaces.
+- Ctrl-C printed a traceback and left temporary files behind.
+
+### Removed
+
+- The on-disk request cache (`~/.docs_to_md/`), which was never reused between runs.
+- The copied documentation for the deprecated Marker endpoint. The docs now link to the live Datalab API reference.
+
+## [0.5.2] - 2026-05-13
+
+### Added
+
+- Fallback handling when the default cache or temp directories are not writable.
+- Test coverage for HTML output CLI configuration.
+- Mocked test coverage for processing both bundled example PDFs.
+- CI and dependency automation configuration in `.github/workflows/ci.yml` and `.github/dependabot.yml`.
+
+### Changed
+
+- Expanded supported input extension and MIME mappings for documents, spreadsheets, presentations, web/ebook files, and images.
+- Improved result polling with per-chunk exponential backoff and cleaner progress handling.
+- Modernized packaging and project metadata in `pyproject.toml`.
+- Refreshed public and contributor documentation.
+
+### Fixed
+
+- Avoided false "unsupported file type" failures by adding MIME detection fallbacks.
+- Fixed a cache retrieval edge case where empty payloads were treated as missing.
+- Improved request/chunk state tracking for completion and failure handling.
+
+## [0.5.1] - 2025-09-29
+
+### Fixed
+
+- Prevented creation of output image directories when no images were returned.
+- Corrected generated filename and image path handling for output assets.
+
+## [0.5.0] - 2025-05-19
+
+### Added
+
+- Unit test coverage for CLI processing paths.
+
+### Changed
+
+- Updated project docs for Datalab Marker API usage and contributor workflow.
+- Refactored processor internals into clearer chunking and submission helper flows.
+- Switched test execution to `unittest`.
+
+### Fixed
+
+- Fixed mutable default list behavior in request/chunk models.
+
+## [0.4.0] - 2025-04-21
+
+### Changed
+
+- Polished post-refactor processing behavior and output handling for the package layout.
+
+### Fixed
+
+- Improved image path deduplication and related output consistency.
+
+## [0.3.0] - 2025-04-19 (unpublished)
+
+### Changed
+
+- Refactored processing, caching, and result handling internals.
+
+## [0.2.1] - 2025-04-10
+
+### Fixed
+
+- Fixed packaging and distribution issues from the first PyPI release.
+
+## [0.2.0] - 2025-04-10
+
+### Added
+
+- First public PyPI release of `pdf-to-markdown-cli`.
+- Package and distribution scaffolding for pip installation and the `pdf-to-md` CLI entrypoint.
+
+### Changed
+
+- Reorganized the project into a publishable Python package.

pdf_to_markdown_cli-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to pdf-to-md
+
+Thanks for your interest in improving `pdf-to-md`! Bug reports, feature ideas, documentation fixes, and pull requests are all welcome.
+
+## Ground rules
+
+- **Reliability over features.** A conversion tool is only useful if you can trust it with a thousand files. Changes should keep runs predictable, re-runnable, and honest about failures.
+- **Keep the CLI scriptable.** Only converted file paths go to stdout, and exit codes carry meaning. Don't print anything else to stdout.
+- **Stay backward-compatible** unless a breaking change is deliberate. Document breaking changes in `CHANGELOG.md` and in the README's upgrade section.
+- **Never commit** API keys, private documents, or build artifacts.
+
+## Getting set up
+
+```bash
+git clone https://github.com/SokolskyNikita/pdf-to-markdown-cli.git
+cd pdf-to-markdown-cli
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Checks
+
+CI runs these on Linux, macOS, and Windows for every supported Python version. Run them before opening a pull request:
+
+```bash
+pytest --cov           # full offline suite; never calls the API
+ruff check .           # lint
+ruff format --check .  # formatting (`ruff format .` fixes it)
+```
+
+### Live API tests
+
+`tests/test_live.py` converts every document in [`examples/`](examples/) with the real Datalab API. It checks text in five languages and scripts, chunk merging, page numbering, images, and the HTML and JSON outputs. These tests are skipped by default. Run them when you change anything that affects conversion output:
+
+```bash
+DATALAB_API_KEY=... pytest -m live    # ~16 pages, a few cents
+```
+
+Maintainers can also run them from the **Live API tests** workflow in the Actions tab, which uses the repository's `DATALAB_API_KEY` secret.
+
+## Project layout
+
+```text
+src/docs_to_md/
+├── cli.py        arguments, entry point, exit codes, summary
+├── config.py     validated runtime configuration
+├── discovery.py  input discovery, deterministic output names
+├── pipeline.py   split, submit concurrently, poll, report
+├── client.py     API client: retries, timeouts, error types
+├── models.py     API request/response types, formats
+├── pdf.py        page ranges and PDF splitting (pikepdf)
+├── assemble.py   merge chunks, renumber pages, write files
+├── markdown.py   Markdown clean-up (reflow, captions)
+├── console.py    terminal output, progress bar, logging
+└── errors.py     exception hierarchy
+tests/            pytest suite; samples.py lists examples/
+examples/         sample documents with reference outputs
+```
+
+## Conventions
+
+- Python 3.10+, type-hinted, with `from __future__ import annotations`.
+- Raise exceptions from `errors.py`. Use `FatalAPIError` only for problems that affect every request (bad key, no credits). It aborts the whole run.
+- Keep network code in `client.py` and orchestration in `pipeline.py`. Pipeline tests use `FakeClient` from `tests/conftest.py`. HTTP behavior is tested with the fake session in `tests/test_client.py`.
+- Add tests with every behavior change, in the module's test file. The suite is fast (under a second), so keep it that way.
+- Update the docs in the same pull request: `README.md` for user-facing changes, `CHANGELOG.md` under **Unreleased**, and `AGENTS.md` when the module map or conventions change.
+
+## Reporting bugs and proposing features
+
+Open an [issue](https://github.com/SokolskyNikita/pdf-to-markdown-cli/issues/new/choose) using the templates. For a bug, the most useful things are the exact command, the input type, and the output of the same command with `-v`. Please don't attach confidential documents.
+
+Report security issues privately as described in [SECURITY.md](SECURITY.md).
+
+## Releasing (maintainers)
+
+1. Move the **Unreleased** changelog notes under a `## [X.Y.Z] - YYYY-MM-DD` heading and bump `version` in `pyproject.toml`.
+2. Commit, push to `main`, and wait for CI to pass.
+3. Tag and push: `git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z`.
+
+The [release workflow](.github/workflows/release.yml) then:
+- checks that the tag matches the package version, runs the tests, and builds the sdist and wheel;
+- creates the GitHub release with both files attached and the changelog section as notes;
+- publishes to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/), with no stored tokens.

pdf_to_markdown_cli-1.0.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md LICENSE CHANGELOG.md CONTRIBUTING.md
+
+# The test suite, with the sample PDFs it uses, so the sdist is testable.
+recursive-include tests *.py
+graft examples
+
+global-exclude *.py[cod] __pycache__ .DS_Store

pdf_to_markdown_cli-1.0.1/PKG-INFO

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: pdf-to-markdown-cli
+Version: 1.0.1
+Summary: Convert PDFs, Office documents, ebooks, and images to Markdown, HTML, or JSON with the Datalab API.
+Author-email: Nikita Sokolsky <sokolx@gmail.com>
+Maintainer-email: Nikita Sokolsky <sokolx@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SokolskyNikita/pdf-to-markdown-cli
+Project-URL: Repository, https://github.com/SokolskyNikita/pdf-to-markdown-cli
+Project-URL: Documentation, https://github.com/SokolskyNikita/pdf-to-markdown-cli#readme
+Project-URL: Issues, https://github.com/SokolskyNikita/pdf-to-markdown-cli/issues
+Project-URL: Changelog, https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/CHANGELOG.md
+Keywords: pdf,markdown,converter,cli,document,ocr,datalab,marker
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pikepdf>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: tqdm>=4.60
+Provides-Extra: test
+Requires-Dist: pytest>=8.3.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pdf-to-markdown-cli[test]; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.1.0; extra == "dev"
+Requires-Dist: ruff>=0.11.0; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">pdf-to-md</h1>
+
+<p align="center">
+  <strong>Turn PDFs, scans, and Office documents into clean Markdown with one command, even 1,000-page books.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/pdf-to-markdown-cli/"><img src="https://img.shields.io/pypi/v/pdf-to-markdown-cli.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/pdf-to-markdown-cli/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+  <a href="https://github.com/SokolskyNikita/pdf-to-markdown-cli/actions/workflows/ci.yml"><img src="https://github.com/SokolskyNikita/pdf-to-markdown-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/SokolskyNikita/pdf-to-markdown-cli/releases"><img src="https://img.shields.io/github/v/release/SokolskyNikita/pdf-to-markdown-cli" alt="GitHub release"></a>
+  <a href="https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
+</p>
+
+`pdf-to-md` is a command-line tool that converts documents to Markdown, HTML, or JSON with the [Datalab](https://www.datalab.to/) Convert API, the hosted version of the open-source [Marker](https://github.com/datalab-to/marker) engine. It handles the tedious parts for you: splitting big PDFs, uploading in parallel, retrying, stitching the results back together, and fixing page numbers and image links.
+
+```console
+$ pdf-to-md books/
+✓ darwin.pdf → darwin.md (516 pages, $1.55)
+✓ tolstoy.pdf → tolstoy.md (537 pages, $1.61)
+✓ grimm.pdf → grimm.md (510 pages, $1.53)
+Done in 4m37s: 3 converted · 1563 pages · $4.69
+```
+
+<sub>Output from a real run (file names shortened): three scanned 19th-century books in English, Russian, and German Fraktur.</sub>
+
+## Why pdf-to-md
+
+- **Built for big documents.** PDFs are split into page chunks that convert in parallel and are merged back into a single file. Page separators, anchors, and image links stay correct across chunks.
+- **Safe to re-run.** Output names are deterministic (`report.pdf` → `report.md`) and finished files are skipped. Re-running on a folder converts only what's new or failed, so you never pay twice by accident.
+- **Honest about results.** Every file reports its pages and cost. The exit code says whether anything failed. A bad API key stops the run immediately instead of failing file by file.
+- **Resilient.** Rate limits, server errors, and dropped connections are retried with backoff. Ctrl-C stops cleanly without leaving half-written files.
+- **Made for scripting.** Converted paths go to stdout, progress and errors to stderr, so it drops straight into pipelines and CI jobs.
+- **Any language, any era.** Tested on modern PDFs, math, and scans of Cyrillic, blackletter German, and vertical classical Chinese ([samples](#sample-conversions)).
+
+## Installation
+
+Requires Python 3.10 or newer. [pipx](https://pipx.pypa.io/) installs it in its own isolated environment:
+
+```bash
+pipx install pdf-to-markdown-cli
+```
+
+`uv tool install pdf-to-markdown-cli` and `pip install pdf-to-markdown-cli` work too.
+
+Then get an API key from [datalab.to/app/keys](https://www.datalab.to/app/keys) and export it:
+
+```bash
+export DATALAB_API_KEY="your_api_key"
+```
+
+## Quick start
+
+```bash
+pdf-to-md report.pdf
+```
+
+This writes `report.md` next to the PDF, plus a `report_images/` folder if the document contains images. That's it.
+
+## Recipes
+
+```bash
+# Mirror a folder tree elsewhere
+pdf-to-md ~/papers -o ~/papers-md
+
+# Preview files and pages, at no cost
+pdf-to-md ~/papers --dry-run
+
+# Best quality for hard scans and tables
+pdf-to-md scan.pdf --mode accurate
+
+# First ten pages plus page 42 (0-based)
+pdf-to-md book.pdf --page-range 0-9,42
+
+# HTML or JSON instead of Markdown
+pdf-to-md slides.pptx --html
+pdf-to-md form.pdf --json
+
+# Mark page boundaries in the output
+pdf-to-md contract.pdf --paginate
+
+# Text only: no images or descriptions
+pdf-to-md manual.pdf --no-images \
+  --no-image-captions
+
+# Redo everything, replacing old outputs
+pdf-to-md ~/papers --overwrite
+
+# Feed converted files to other tools
+pdf-to-md ~/papers -q | xargs wc -w
+```
+
+## How it works
+
+1. **Plan.** Inputs are discovered recursively. Hidden files and folders this tool generated earlier are ignored. Each input gets a deterministic output path, and inputs whose output already exists are skipped.
+2. **Split.** PDFs are cut into chunks of `--chunk-size` pages (default 25). Page selection with `--page-range` or `--max-pages` happens here, so only those pages are uploaded and billed. Other formats are uploaded whole.
+3. **Convert.** Up to `--concurrency` chunks (default 5) are processed at once. Each one is uploaded and then polled until it's done. Throttling and server errors are retried, honoring the API's `Retry-After`.
+4. **Merge.** Chunk results are joined in page order. Page separators, HTML page ids, JSON block ids, and in-document anchors are renumbered to match the original document. Images are renamed so they never collide, and links to them are URL-encoded.
+5. **Write.** The output is written to a temporary file and renamed into place, so an interrupted run never leaves a partial file behind.
+
+## Output
+
+```text
+papers/
+├── report.pdf
+├── report.md       ← the document
+└── report_images/  ← images, if any
+```
+
+- If two inputs would produce the same name (`a.pdf` and `a.docx`), both keep their source extension: `a.pdf.md` and `a.docx.md`. Names are compared case-insensitively, and an output never overwrites an input.
+- Hard-wrapped paragraph lines are joined in Markdown output (disable with `--keep-line-breaks`). Image descriptions live in the image alt text.
+
+## Supported formats
+
+| Input | Extensions |
+| --- | --- |
+| PDF | `.pdf` (split into chunks) |
+| Word processing | `.doc` `.docx` `.odt` |
+| Presentations | `.ppt` `.pptx` `.odp` |
+| Spreadsheets | `.xls` `.xlsx` `.xlsm` `.xltx` `.ods` `.csv` |
+| Web and ebooks | `.html` `.htm` `.epub` |
+| Images | `.png` `.jpg` `.jpeg` `.webp` `.gif` `.tiff` `.tif` |
+
+Outputs are Markdown (`.md`, the default), HTML (`.html`), or JSON (`.json`, Marker's block tree with page and position data). The API accepts files of up to 200 MB. Non-PDF files are always sent as a single request.
+
+## Quality, speed, and cost
+
+`--mode` picks a Datalab processing mode:
+
+| Mode | Use it for |
+| --- | --- |
+| `fast` (API default) | Clean digital PDFs and good scans. |
+| `balanced` | Mixed documents with tables, forms, or harder layouts. |
+| `accurate` | The hardest material: poor scans, dense tables, handwriting. |
+
+Every result line shows what Datalab billed, and the run summary adds it up. In our September 2026 test runs, conversions cost about 0.3¢ per page ($3 per 1,000 pages). See [Datalab's pricing](https://www.datalab.to/pricing) for current rates.
+
+Throughput depends on your plan's limits. With the default of 5 concurrent requests (the free tier's limit), the 1,563-page run above took 4 minutes 37 seconds. Paid plans allow far more concurrency, so raise `-j` to match yours.
+
+## Sample conversions
+
+[`examples/`](https://github.com/SokolskyNikita/pdf-to-markdown-cli/tree/main/examples) holds sample documents next to their actual output from this tool:
+
+| Sample (links to output) | Language | What it tests |
+| --- | --- | --- |
+| [Alice in Wonderland](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/examples/alice_in_wonderland_sample.md) | English | Illustrated novel, curly quotes |
+| [Algebraic geometry notes](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/examples/equations.md) | English | Mathematics rendered as LaTeX |
+| [*Origin of Species* (1859)](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/examples/darwin_origin_of_species_en.md) | English | Old scan, fold-out tree diagram |
+| [*War and Peace* (1937 ed.)](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/examples/tolstoy_war_and_peace_ru.md) | Russian | Cyrillic mixed with French, footnotes |
+| [*Grimm's Fairy Tales* (1857)](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/examples/grimm_fairy_tales_de.md) | German | Fraktur blackletter typeface |
+| [*Shijing Gupu* (1908)](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/examples/shijing_gupu_zh.md) | Chinese | Vertical text, music notation |
+
+See [examples/README.md](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/examples/README.md) for sources and how the samples are used in tests.
+
+## Command reference
+
+```text
+pdf-to-md INPUT [INPUT ...] [options]
+```
+
+`INPUT` is any mix of files and directories. The tool also runs as `python -m docs_to_md`.
+
+**Output**
+
+| Option | Description |
+| --- | --- |
+| `-f`, `--format FMT` | `markdown` (default), `html`, or `json`. `--html` and `--json` are shortcuts. |
+| `-o`, `--output-dir DIR` | Write here instead of next to each input. Folder structure under directory inputs is mirrored. |
+| `--overwrite` | Replace existing outputs instead of skipping those inputs. |
+| `--keep-line-breaks` | Keep hard-wrapped paragraph lines in Markdown. |
+
+**Conversion**
+
+| Option | Description |
+| --- | --- |
+| `-m`, `--mode MODE` | `fast` (the API default), `balanced`, or `accurate`. |
+| `--paginate` | Insert page separators. |
+| `--no-images` | Don't extract images. |
+| `--no-image-captions` | Don't generate image descriptions. |
+| `--skip-cache` | Ignore Datalab's server-side cache of previous results. |
+| `--api-option KEY=VALUE` | Send any other [Convert API](https://documentation.datalab.to/api-reference/convert-document) field. Repeatable, e.g. `--api-option extras=extract_links`. |
+
+**Pages and chunking**
+
+| Option | Description |
+| --- | --- |
+| `--page-range RANGE` | 0-based pages to convert, e.g. `0,5-10`. |
+| `--max-pages N` | Convert at most `N` pages of each document. |
+| `--chunk-size N` | PDF pages per request. Default: `25`. Smaller chunks mean more parallelism but more requests. |
+| `--no-chunk` | Send each PDF as one request. |
+
+**Run control**
+
+| Option | Description |
+| --- | --- |
+| `--api-key KEY` | API key. Prefer the environment variable, which keeps the key out of shell history. |
+| `-j`, `--concurrency N` | Requests in flight at once. Default: `5`. |
+| `--timeout SECONDS` | Give up on a single request after this long. Default: `3600`. |
+| `-n`, `--dry-run` | Show what would be converted, with page and chunk counts. Makes no API calls and needs no key. |
+| `-q`, `--quiet` | Print only errors (converted paths still go to stdout). |
+| `-v`, `--verbose` | Print debug logs, including every API call and retry. |
+| `--version` | Print the version and exit. |
+
+## Scripting and automation
+
+Only converted file paths are printed to stdout, one per line. Status lines, the progress bar, and errors go to stderr.
+
+| Exit status | Meaning |
+| --- | --- |
+| `0` | Every input was converted or skipped. |
+| `1` | At least one file failed; the rest were still converted. |
+| `2` | Usage or configuration error, including a rejected API key or an exhausted account. |
+| `130` | Interrupted with Ctrl-C. |
+
+Because finished files are skipped, the simplest way to retry failures in an interrupted batch is to run the same command again.
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `DATALAB_API_KEY` | API key, the same variable Datalab's SDK uses. The pre-1.0 name `MARKER_PDF_KEY` also works. `--api-key` overrides both. |
+| `NO_COLOR` | Disable colored output. |
+
+The tool keeps no state between runs. Temporary chunk files live in the system temp directory and are deleted when the run ends.
+
+## Troubleshooting
+
+| Message | What to do |
+| --- | --- |
+| `No API key found` | Set `DATALAB_API_KEY`. |
+| `Authentication failed` | The key was rejected. Check it on the [Datalab dashboard](https://www.datalab.to/app/keys). |
+| `Payment required` | Your Datalab account is out of credits. |
+| `exists (use --overwrite)` | The output is already there. Add `--overwrite` to redo it. |
+| `timed out` | A request took longer than `--timeout`. Raise it, or lower `--chunk-size`. |
+| Frequent throttling | You're above your plan's limits (the free tier allows 10 requests per minute). Lower `-j`. |
+
+Anything else: rerun with `-v` and [open an issue](https://github.com/SokolskyNikita/pdf-to-markdown-cli/issues) with the output.
+
+## Upgrading from 0.x
+
+Version 1.0 moved to Datalab's current `/api/v1/convert` endpoint and fixed `--html` and `--json`, which produced no output in 0.5.x.
+
+- Outputs are now `report.md` + `report_images/` instead of `report_<random>.md` + `images_<random>/`, and existing outputs are skipped unless you pass `--overwrite`.
+- `-o` accepts relative paths and mirrors folder structure.
+- `--llm` now means `--mode balanced` and `--max` means `--mode accurate`. Datalab removed the options behind `--strip`, `--force`, and `--langs`, so those flags are ignored with a warning.
+- `--pages`, `--noimg`, `-cs`, and `-mp` still work as aliases of `--paginate`, `--no-images`, `--chunk-size`, and `--max-pages`.
+- Failures now exit non-zero, and `~/.docs_to_md/` is no longer used and can be deleted.
+
+Full details are in the [changelog](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/CHANGELOG.md).
+
+## Contributing
+
+Bug reports, ideas, and pull requests are welcome. [CONTRIBUTING.md](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/CONTRIBUTING.md) covers setup, the test suites (including the opt-in live API tests), and the release process.
+
+## Acknowledgements
+
+Conversion quality comes from [Marker](https://github.com/datalab-to/marker) and the [Datalab](https://www.datalab.to/) API. This is an independent project and isn't affiliated with Datalab.
+
+## License
+
+[MIT](https://github.com/SokolskyNikita/pdf-to-markdown-cli/blob/main/LICENSE) © Nikita Sokolsky