Convert PDF to Markdown

A Node.js package and CLI tool that converts PDF files to Markdown using OpenAI's vision API. This tool extracts text, tables, charts, and images from scanned PDFs and converts them into well-structured Markdown format.

Features

• 📄 Convert PDF files (including scanned documents) to Markdown
• 🧠 Uses OpenAI vision API for accurate OCR and content understanding
• 🖼️ Handles tables, charts, and images with proper descriptions
• ⚡ Batch processing of multiple pages
• 🛠️ Configurable image quality and processing options
• 📦 Available as both npm package and CLI tool

Installation

As npm package

npm install pdf-to-md

As CLI tool (global)

npm install -g pdf-to-md

Usage

As npm package

import { Converter } from 'pdf-to-md';
import OpenAI from 'openai';
import { promises as fs } from 'fs';

// Initialize OpenAI client
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL
});

// Configure conversion options
const openaiRequest = {model: 'gpt-4o'}; // Must be a vision-capable model

// Create converter instance
const converter = new Converter(openai, openaiRequest);

// Convert PDF to markdown
const pdfBuffer = await fs.readFile('document.pdf');
const markdown = await converter.toMarkdown(pdfBuffer);
console.log(markdown);

As CLI tool

# Set environment variables for any OpenAI-compatible API
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://api.openai.com/v1"

# Convert PDF
pdf-to-md path/to/document.pdf

CLI Options

CLI flags mirror the converter options documented below. Use either camelCase (for example --maxPages) or kebab-case (--max-pages). Examples:

pdf-to-md path/to/document.pdf --maxPages 5 --temperature 0.2
pdf-to-md path/to/document.pdf --max-file-size 10485760 --temp-dir ./tmp

Supported flags include:

• --maxPages <number>: Limit the number of PDF pages processed.
• --maxFileSize <bytes>: Reject PDFs larger than the provided byte size.
• --viewportScale <number>: Control the render scale when rasterizing pages.
• --maxImageWidth <pixels> / --maxImageHeight <pixels>: Resize images before OCR.
• --tempDir <path>: Override the temporary working directory.
• --model <name>: Override the OpenAI-compatible model name.
• --temperature <number>: Override the completion temperature.
• --maxTokens <number>: Override the max_tokens request option.

Configuration

Converter Options

interface ConverterOptions {
  maxFileSize?: number;    // Buffer size limit in bytes (default: 50MB)
  maxPages?: number;       // Maximum pages to process (default: 20)
  viewportScale?: number;  // PDF to PNG scale (default: 3)
  maxImageWidth?: number;  // Maximum image width (default: 2000)
  maxImageHeight?: number; // Maximum image height (default: 2000)
  model?: string;          // OpenAI model (default: 'gpt-4o')
  temperature?: number;    // Generation temperature (default: 0.01)
  maxTokens?: number;      // Maximum tokens (default: 4000)
}

API Reference

Converter class

Constructor

new Converter(openaiClient, openaiRequest, options?)

• openaiClient: OpenAI client instance
• openaiRequest: OpenAI request configuration
• options: Optional converter options

Methods

toMarkdown(pdfFileBuffer): Promise<string>

Converts a PDF buffer to Markdown string.

• pdfFileBuffer: Buffer containing PDF data
• Returns: Promise resolving to Markdown string

Development

Setup

Clone the repository and install dependencies:

# Clone repository
git clone [email protected]:zhf/pdf-to-md.git
cd pdf-to-md

# Install dependencies
npm install

# Build project
npm run build

# Run CLI in development
npm run dev path/to/document.pdf

Scripts

• npm run build: Compile TypeScript to JavaScript
• npm run clean: Remove build output
• npm run dev <pdf-path>: Run CLI in development mode
• npm run start <pdf-path>: Run compiled CLI
• npm run prepublishOnly: Clean and build before publishing

Requirements

• Node.js >= 16.0.0
• OpenAI API key with vision capabilities
• Sharp (for image processing)

License

MIT

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.