PDF2MJ

Convert PDF documents to Markdown and structured JSON for RAG pipelines, LLM preprocessing, and knowledge bases.

Installation (For Users)

PyPI: pdf2mj is not published on PyPI yet. Install from source (see Development Setup) or publish the package first.

When available on PyPI:

pip install pdf2mj

With OCR support:

pip install "pdf2mj[ocr]"

OCR Requirements

OCR is optional and requires:

• Tesseract OCR installed on your system
• OCR extras installed via:

pip install "pdf2mj[ocr]"

First Run

On the first pdf2mj invocation (no arguments), a Rich-powered welcome screen is shown once. State is stored in:

• Linux/macOS: ~/.config/pdf2mj/config.json
• Windows: %APPDATA%\pdf2mj\config.json

pdf2mj welcome   # show the welcome screen again
pdf2mj doctor    # verify dependencies and environment

Quick Start

Convert a PDF to Markdown and JSON:

pdf2mj document.pdf

Output files are generated next to the source PDF:

document.md
document.json

Specify an output directory:

pdf2mj document.pdf --output ./output

Common Examples

Generate all outputs:

pdf2mj document.pdf --all --output ./output

Extract images:

pdf2mj document.pdf --extract-images

Generate RAG chunks:

pdf2mj document.pdf --chunk-size 1000

Use OCR for scanned PDFs:

pdf2mj document.pdf --ocr

CLI Options

Flag	Description
--markdown / --no-markdown	Generate Markdown (default: on)
--json / --no-json	Generate structured JSON (default: on)
--ocr	OCR scanned pages
--extract-images	Extract embedded images
--figures	Alias for --extract-images
--chunk-size N	Generate RAG chunks
--chunk-overlap N	Chunk overlap (default: 200)
--output, -o	Output directory
--verbose, -v	Detailed logging
--metadata	Export metadata JSON
--tables / --no-tables	Extract tables
--all	Enable all supported outputs

Utility Commands

Command	Description
pdf2mj welcome	Show the onboarding welcome screen
pdf2mj doctor	Check Python, dependencies, OCR, and write access

Development Setup (For Contributors)

Prerequisites

• Python 3.12+
• Git
• Optional: Tesseract OCR

Clone the Repository

git clone https://github.com/Ronit-Pai/pdf2mj.git
cd pdf2mj

Create a Development Environment

Using pip:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

pip install -e ".[dev]"

Using uv:

uv venv
source .venv/bin/activate

uv pip install -e ".[dev]"

With OCR support:

pip install -e ".[dev,ocr]"

Running Tests

pytest

Coverage:

pytest --cov=pdf2mj --cov-report=html

Project Structure

src/pdf2mj/
  cli.py
  config.py
  welcome.py
  doctor.py
  converter.py
  models.py
  markdown.py
  json_export.py
  metadata.py
  table_extractor.py
  image_extractor.py
  ocr.py
  chunker.py
  console_util.py

tests/
sample_pdfs/

Local Development

Run directly from source:

pdf2mj sample.pdf

or

python -m pdf2mj sample.pdf