Metadata-Version: 2.4
Name: documint2md
Version: 2.0.2
Summary: Convert PDF, DOCX, CSV, and image files to Markdown.
Author: documint2md Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/myucordero/documint2md
Project-URL: Repository, https://github.com/myucordero/documint2md
Project-URL: Issues, https://github.com/myucordero/documint2md/issues
Keywords: markdown,pdf,docx,csv,cli
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4==4.14.3
Requires-Dist: lxml==6.1.0
Requires-Dist: mammoth==1.11.0
Requires-Dist: markdownify==1.2.2
Requires-Dist: pandas==2.3.3
Requires-Dist: pdfminer.six==20251230
Requires-Dist: prompt-toolkit==3.0.48
Requires-Dist: tabulate==0.9.0
Provides-Extra: dev
Requires-Dist: pytest==9.0.3; extra == "dev"
Requires-Dist: pip-tools==7.5.3; extra == "dev"
Requires-Dist: build==1.4.0; extra == "dev"
Requires-Dist: backports.tarfile==1.2.0; python_version < "3.12" and extra == "dev"
Requires-Dist: colorama==0.4.6; sys_platform == "win32" and extra == "dev"
Requires-Dist: importlib-metadata==9.0.0; python_version < "3.12" and extra == "dev"
Requires-Dist: pywin32-ctypes==0.2.3; sys_platform == "win32" and extra == "dev"
Requires-Dist: setuptools==81.0.0; extra == "dev"
Requires-Dist: twine==6.2.0; extra == "dev"
Requires-Dist: zipp==3.23.0; python_version < "3.12" and extra == "dev"
Provides-Extra: pdftext
Requires-Dist: pdftext==0.6.3; extra == "pdftext"
Provides-Extra: marker
Requires-Dist: marker-pdf==1.10.1; extra == "marker"
Provides-Extra: pymupdf4llm
Requires-Dist: pymupdf4llm==1.27.2.3; extra == "pymupdf4llm"
Provides-Extra: markdown
Requires-Dist: mdformat==1.0.0; extra == "markdown"
Requires-Dist: mdformat-gfm==1.0.0; extra == "markdown"
Provides-Extra: universal-lite
Requires-Dist: markitdown==0.1.5; extra == "universal-lite"
Provides-Extra: docling
Requires-Dist: docling==2.92.0; extra == "docling"
Provides-Extra: universal
Requires-Dist: docling==2.92.0; extra == "universal"
Requires-Dist: markitdown==0.1.5; extra == "universal"
Provides-Extra: pypdfium2
Requires-Dist: pypdfium2==4.30.0; extra == "pypdfium2"
Provides-Extra: ocr
Requires-Dist: paddleocr==3.4.0; extra == "ocr"
Requires-Dist: paddlepaddle==3.2.2; extra == "ocr"
Requires-Dist: pypdfium2==4.30.0; extra == "ocr"
Requires-Dist: pi-heif==0.15.0; extra == "ocr"
Provides-Extra: all
Requires-Dist: pdftext==0.6.3; extra == "all"
Requires-Dist: pymupdf4llm==1.27.2.3; extra == "all"
Requires-Dist: mdformat==1.0.0; extra == "all"
Requires-Dist: mdformat-gfm==1.0.0; extra == "all"
Requires-Dist: docling==2.92.0; extra == "all"
Requires-Dist: markitdown==0.1.5; extra == "all"
Requires-Dist: pypdfium2==4.30.0; extra == "all"
Requires-Dist: paddleocr==3.4.0; extra == "all"
Requires-Dist: paddlepaddle==3.2.2; extra == "all"
Requires-Dist: pi-heif==0.15.0; extra == "all"
Requires-Dist: setuptools==81.0.0; extra == "all"
Dynamic: license-file

# documint2md

Convert PDF, DOCX, CSV, and image files to Markdown from the command line or from Python.

`documint2md` installs the `doc2md` CLI and the `doc2md` Python package. It is designed for scripts, agents, and documentation pipelines that need predictable Markdown output and clear machine-readable status.

## Install

```bash
python -m pip install documint2md
```

Optional extras:

```bash
python -m pip install "documint2md[markdown]"       # GFM Markdown formatting
python -m pip install "documint2md[pymupdf4llm]"    # alternate PDF Markdown engine
python -m pip install "documint2md[universal-lite]" # MarkItDown for extra formats
python -m pip install "documint2md[docling]"        # Docling structured conversion
python -m pip install "documint2md[ocr]"            # image and scanned-PDF OCR
python -m pip install "documint2md[all]"            # all published optional features
```

Python 3.11 or newer is required.

## Command Line

Convert one file and write `<input stem>.md` beside it:

```bash
doc2md report.pdf
doc2md notes.docx
doc2md table.csv
doc2md scan.png
```

Choose an output path:

```bash
doc2md report.pdf -o report.md
```

Write Markdown to stdout:

```bash
doc2md report.pdf -o -
```

Preview without writing a file:

```bash
doc2md report.pdf --preview
```

Run several inputs non-interactively:

```bash
doc2md docs/*.pdf --yes
```

Open the interactive picker:

```bash
doc2md
```

## Agent and Automation Usage

Use `--json` when another program needs a structured result. Diagnostics still go to stderr, and stdout stays reserved for JSON in this mode.

```bash
doc2md report.pdf --json
doc2md report.pdf --dry-run --json
```

Useful automation flags:

```bash
doc2md report.pdf --quiet
doc2md report.pdf --debug
doc2md report.pdf --stats
doc2md doctor engines --json
```

Exit codes:

- `0`: success
- `2`: usage or argument error
- `3`: unsupported format
- `4`: conversion failed
- `5`: output write failed

Output behavior:

- By default, `report.pdf` writes `report.md` in the same directory.
- `-o <file>` writes UTF-8 Markdown with `\n` newlines.
- `-o -` writes Markdown to stdout.
- Errors and diagnostics go to stderr.

## Formats and Engines

Default conversions:

- PDF: text extraction with `pdfminer.six`
- DOCX: Mammoth HTML to Markdown
- CSV: Pandas to Markdown table
- Images: OCR when the `ocr` extra is installed

Force a format:

```bash
doc2md input.bin --format pdf
doc2md input.bin --format docx
doc2md input.bin --format csv
doc2md input.bin --format image
```

Use optional engines:

```bash
doc2md report.pdf --engine pymupdf4llm
doc2md slides.pptx --format any --engine markitdown
doc2md document.docx --format any --engine docling
```

Check installed optional engines:

```bash
doc2md doctor engines
doc2md doctor engines --json
```

## Markdown Formatting

Every CLI conversion can post-process Markdown:

```bash
doc2md table.csv --md-style normalize
doc2md table.csv --md-style gfm
doc2md table.csv --md-style none
```

- `normalize` is the default. It normalizes newlines, strips trailing whitespace, caps blank lines, and ends non-empty output with one trailing newline.
- `gfm` formats GitHub Flavored Markdown and requires `documint2md[markdown]`.
- `none` leaves converter output unchanged after conversion.

## OCR

Install OCR support:

```bash
python -m pip install "documint2md[ocr]"
```

Convert an image:

```bash
doc2md scan.png --ocr-lang en
```

Use OCR for scanned or low-text PDFs:

```bash
doc2md scan.pdf --ocr-mode auto --ocr-lang en
doc2md scan.pdf --ocr-mode always --ocr-layout heuristic --md-style gfm
```

Common OCR options:

```bash
doc2md scan.pdf --ocr-device cpu
doc2md scan.pdf --ocr-device gpu:0
doc2md scan.pdf --ocr-render-scale 2.0
doc2md scan.pdf --ocr-min-score 0.5
doc2md scan.pdf --ocr-debug-json debug.json
doc2md scan.png --ocr-debug-image debug.png
```

The first OCR run may download model files for the OCR backend. Subsequent runs are normally faster.

## Python API

```python
from doc2md import (
    any_to_markdown,
    csv_to_markdown,
    docx_to_markdown,
    image_to_markdown,
    pdf_to_markdown,
)

markdown = pdf_to_markdown("report.pdf")
```

Each public converter accepts `str` or `PathLike` input and returns `str`.

```python
from doc2md import ConversionError, UnsupportedFormatError, pdf_to_markdown

try:
    markdown = pdf_to_markdown("report.pdf")
except UnsupportedFormatError as exc:
    print(f"Unsupported input: {exc}")
except ConversionError as exc:
    print(f"Conversion failed: {exc}")
```

## Profiles

Store reusable defaults in `doc2md.toml`:

```toml
[profiles.fast_pdf]
format = "pdf"
engine = "pdfminer"
md_style = "normalize"

[profiles.ocr_pdf]
format = "pdf"
ocr_mode = "auto"
ocr_lang = "en"
ocr_layout = "heuristic"
md_style = "gfm"
```

Run with a profile:

```bash
doc2md report.pdf --profile fast_pdf
doc2md scan.pdf --profile ocr_pdf
```

## Notes for Reliable Automation

- Pin the package version in production, for example `documint2md==2.0.2`.
- Use `--json` for structured status and `-o -` only when stdout should contain Markdown.
- Use `--yes` for batch conversions in non-interactive jobs.
- Use `--md-style normalize` or `--md-style gfm` when exact Markdown formatting matters.
- Run `doc2md doctor engines --json` in setup checks to confirm optional engines are installed.

## Links

- PyPI project: <https://pypi.org/project/documint2md/>
- Source repository: <https://github.com/myucordero/documint2md>
