Skip to content
BranchesTags

Repository files navigation

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.

About

About Javascript tool for converting files and office documents to Markdown.

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages