markitdown-node

A powerful TypeScript document extraction library that converts 20+ file formats into structured JSON and Markdown.

Features

• 📄 20+ Format Support: Documents (PDF, DOCX, PPTX, XLSX), Web (HTML, RSS, Atom), Images (OCR), Media (Audio, YouTube), Code (Jupyter), Archives (ZIP), Search (Bing SERP), and more
• 🔄 Unified API: Simple, consistent interface for all formats
• 📊 Dual Output: Auto-generates both JSON and Markdown from a single conversion
• 🎯 TypeScript: Full type safety and IntelliSense support
• 🚀 Zero Config: Works out of the box with sensible defaults
• 🖼️ OCR Support: Extract text from images using Tesseract.js (110+ languages)
• 🎙️ Audio Transcription: Convert audio files to text (via LLM integration)
• 📦 pnpm Workspace: Optimized development experience with automatic linking

Installation

For Users

npm install markitdown-node
# or
pnpm install markitdown-node

For Development

This project uses pnpm workspace for better development experience:

# Install pnpm if you haven't
npm install -g pnpm

# Clone and setup
git clone https://github.com/leoning60/markitdown-node.git
cd markitdown-node
pnpm install
pnpm run build

Quick Start

import { MarkItDown } from 'markitdown-node';

const converter = new MarkItDown();
const result = await converter.convert('./document.docx');

if (result.status === 'success') {
  console.log(result.markdown_content);  // ✨ Auto-generated Markdown
  console.log(result.json_content);      // ✨ Auto-generated JSON
}

One-liner conversions:

import { convertToMarkdown, convertToJSON } from 'markitdown-node';

const markdown = await convertToMarkdown('./document.pdf');
const json = await convertToJSON('./data.xlsx');

Supported Formats

| Category | Formats | Notes | |----------|---------|-------| | Documents | PDF, DOCX, PPTX, XLSX | Office documents and spreadsheets | | Web | HTML, RSS, Atom | Web pages and feeds | | Images | PNG, JPEG, TIFF | With EXIF metadata and OCR | | Media | Audio (WAV, MP3, etc.), YouTube | Audio transcription via LLM, YouTube transcripts | | Code | Jupyter Notebooks (.ipynb) | Markdown cells, code, and outputs | | Text | TXT, CSV, JSON, XML | Plain text and structured data | | Subtitles | SRT, VTT | Subtitle files | | Archives | ZIP | Recursive extraction | | Search | Bing SERP | Search result pages |

Usage Examples

Convert Documents

const converter = new MarkItDown();

// PDF to Markdown
const pdf = await converter.convert('./report.pdf');

// Excel to JSON
const excel = await converter.convert('./data.xlsx');
console.log(excel.json_content); // Table structure

// Image with OCR
const image = await converter.convert('./document.png');
console.log(image.markdown_content); // Extracted text

CSV and JSON Files

// CSV → Table structure
const csv = await converter.convert('./data.csv');
// Outputs Markdown table and structured JSON

// JSON → Formatted output
const json = await converter.convert('./config.json');
// Pretty-printed code block with extracted fields

XML, RSS, and Atom Feeds

// Generic XML
const xml = await converter.convert('./config.xml');

// RSS Feed → Structured articles
const rss = await converter.convert('./feed.rss');
// Channel metadata + all articles

// Atom Feed → Structured entries
const atom = await converter.convert('./feed.atom');

Extract from Archives

// Requires: pnpm install unzipper
const result = await converter.convert('./archive.zip');
// All files in ZIP are extracted and converted

YouTube Transcripts

// Requires: pnpm install youtube-transcript
const converter = new MarkItDown({
  defaultOptions: {
    enableTranscript: true,
    transcriptLanguage: 'en',
  },
});

const result = await converter.convert(youtubeHTML, {
  url: 'https://www.youtube.com/watch?v=VIDEO_ID',
});

Audio Transcription

// Requires LLM configuration (OpenAI, etc.)
const result = await converter.convert('./audio.wav');
console.log(result.markdown_content); // Transcribed text

Jupyter Notebooks

const result = await converter.convert('./notebook.ipynb');
// Markdown cells, code cells, and outputs are preserved

Bing SERP

// Extract search results from Bing HTML
const result = await converter.convert('./bing-results.html');
// Structured search results with titles, URLs, descriptions

Custom Options

const converter = new MarkItDown({
  defaultOptions: {
    ocrLanguages: 'chi_sim+eng', // OCR: Chinese + English
    extractImages: true,
    extractTables: true,
  },
});

Running Examples

This project uses pnpm workspace. Examples automatically use the local package:

# First time setup
pnpm install
pnpm run build

# Run examples
cd examples
node 01-quick-start.js          # Basic usage
node 02-all-formats.js          # All supported formats
node 03-docx-example.js         # Word documents
node 04-pdf-example.js          # PDF documents
node 05-image-example.js        # OCR from images
node 06-excel-example.js        # Excel spreadsheets
node 07-powerpoint-example.js   # PowerPoint presentations
node 08-html-example.js         # HTML pages
node 09-subtitle-example.js     # Subtitle files
node 10-convenience-functions.js # Convenience functions
node 11-ocr-languages.js       # OCR with multiple languages
node 12-bing-serp-example.js    # Bing SERP results
node 13-ipynb-example.js       # Jupyter Notebooks
node 14-csv-json-example.js    # CSV and JSON files

After modifying source code, just rebuild:

pnpm run build
cd examples
node 01-quick-start.js  # Automatically uses latest build

See examples/README.md for more details.

OCR Configuration

Images are processed with Tesseract.js OCR, supporting 110+ languages.

Configure Languages

const converter = new MarkItDown({
  defaultOptions: {
    ocrLanguages: 'chi_sim+eng' // Default: Chinese + English
  }
});

// English only
ocrLanguages: 'eng'

// Japanese + English
ocrLanguages: 'jpn+eng'

// Multiple languages
ocrLanguages: 'chi_sim+eng+fra'

Common Language Codes

| Language | Code | Language | Code | |----------|------|----------|------| | English | eng | Spanish | spa | | Chinese (Simplified) | chi_sim | French | fra | | Chinese (Traditional) | chi_tra | German | deu | | Japanese | jpn | Italian | ita | | Korean | kor | Portuguese | por | | Russian | rus | Arabic | ara | | Hindi | hin | Thai | tha | | Vietnamese | vie | Turkish | tur |

📖 Full language list (110+ languages supported)

Optional Dependencies

Some formats require additional packages:

# For ZIP file support
pnpm install unzipper

# For YouTube transcript extraction
pnpm install youtube-transcript

# For audio transcription (LLM-based)
# Configure your LLM provider (OpenAI, etc.) in the options

API Types

ConversionResult

interface ConversionResult {
  status: 'success' | 'error';
  document?: Document;           // Structured document object
  json_content?: DocumentItem[]; // ✨ Auto-generated JSON
  markdown_content?: string;     // ✨ Auto-generated Markdown
  errors?: string[];
  warnings?: string[];
}

Document Structure

interface Document {
  metadata: {
    filename: string;
    format: InputFormat;
    title?: string;
    author?: string;
    // ... more metadata
  };
  content: DocumentItem[]; // Array of content items
}

interface DocumentItem {
  type: 'text' | 'heading' | 'paragraph' | 'list' | 'table' | ...;
  text?: string;
  level?: number;
  children?: DocumentItem[];
  // ... more fields
}

InputFormat Enum

enum InputFormat {
  // Documents
  PDF = 'pdf',
  DOCX = 'docx',
  PPTX = 'pptx',
  XLSX = 'xlsx',
  
  // Web & Feeds
  HTML = 'html',
  RSS = 'rss',
  ATOM = 'atom',
  
  // Text & Data
  TEXT = 'text',
  CSV = 'csv',
  JSON = 'json',
  XML = 'xml',
  
  // Media
  IMAGE = 'image',
  AUDIO = 'audio',
  YOUTUBE = 'youtube',
  
  // Code & Archives
  IPYNB = 'ipynb',
  ZIP = 'zip',
  
  // Subtitles
  SUBTITLE = 'subtitle',
  
  // Special
  BINGSERP = 'bingserp',
}

Development

This project uses pnpm workspace:

# Install dependencies
pnpm install

# Build
pnpm run build

# Watch mode
pnpm run dev

# Type check
pnpm run typecheck

# Clean build artifacts
pnpm run clean

# Rebuild from scratch
pnpm run rebuild

Publishing

# Dry run to check what will be published
pnpm run publish:dry-run

# Release (bumps version, commits, tags, and publishes)
pnpm run release

Project Structure

markitdown-node/
├── pnpm-workspace.yaml    # Workspace configuration
├── package.json            # Main package
├── src/                    # Source code
│   ├── converter.ts        # Main converter class
│   ├── backends/           # Format-specific backends
│   ├── exporters/          # JSON and Markdown exporters
│   └── types/              # TypeScript types
├── dist/                   # Built output (generated)
├── examples/               # Example usage (workspace package)
│   ├── package.json        # Uses "workspace:*" dependency
│   └── *.js                # Example files
└── README.md               # This file

License

MIT

Acknowledgments

Inspired by markitdown by Microsoft.