pdf2mj 0.1.0

Convert PDF documents to Markdown and structured JSON for RAG and LLM pipelines

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