markitdown-ts

A TypeScript port of Microsoft's markitdown Python library. Converts documents to Markdown.

Supported Formats

Format	Extensions	Notes
Plain text	.txt, .text, .md, .markdown, .json, .jsonl, .xml, .yaml, .yml, .toml, .ini, .cfg, .conf, .log, .env	Charset detection via iconv-lite
CSV	.csv	Converts to Markdown tables
HTML	.html, .htm	Cheerio + Turndown with GFM tables
DOCX	.docx	Via mammoth
XLSX / XLS	.xlsx, .xls	Via SheetJS
PDF	.pdf	Dual-engine: pdfplumber-wasm for tables/forms, pdf-parse fallback
PPTX	.pptx	Extracts text, tables, charts, image alt text, notes
Jupyter Notebooks	.ipynb	Code cells, markdown cells, outputs
EPUB	.epub	Metadata + chapter content
ZIP	.zip	Recursively converts contained files
RSS / Atom	.xml, .rss, .atom	Feed metadata and article content
Outlook MSG	.msg	Email headers and body
Images	.jpg, .jpeg, .png	Metadata via exiftool (optional), LLM descriptions (optional)
Audio	.wav, .mp3, .m4a, .mp4	Metadata via exiftool (optional)
Wikipedia	wikipedia.org URLs	Extracts article content, removes navigation
YouTube	youtube.com/watch URLs	Video metadata + transcript fetching
Bing SERP	bing.com/search URLs	Search result extraction

Installation

bun add markitdown-typescript

Usage

import { createMarkItDown } from "markitdown-typescript";

const md = createMarkItDown();

// Convert a local file
const result = await md.convert("document.docx");
console.log(result.markdown);
console.log(result.title);

// Convert a buffer
const buffer = await fs.promises.readFile("spreadsheet.xlsx");
const result = await md.convert(buffer, {
  streamInfo: { mimetype: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" },
});

// Convert a URL
const result = await md.convert("https://en.wikipedia.org/wiki/TypeScript");

// Convert a data URI
const result = await md.convert("data:text/plain;base64,SGVsbG8gV29ybGQ=");

Options

const md = createMarkItDown({
  // Keep data URIs in images instead of truncating
  keepDataUris: true,

  // Exiftool path for image/audio metadata extraction
  exiftoolPath: "/usr/local/bin/exiftool",

  // LLM client for image descriptions (OpenAI-compatible API)
  llmClient: openaiClient,
  llmModel: "gpt-4o",
  llmPrompt: "Describe this image in detail.",

  // Custom mammoth style mapping for DOCX conversion
  styleMap: "p[style-name='Quote'] => blockquote:fresh",

  // Preferred languages for YouTube transcript fetching
  youtubeTranscriptLanguages: ["en", "es"],
});

Custom Converters

import { createMarkItDown, converter, byExt } from "markitdown-typescript";

const myConverter = converter(
  "MyFormat",
  byExt(".myext"),
  async (ctx) => {
    const text = new TextDecoder().decode(ctx.buffer);
    return { markdown: `# Custom\n\n${text}` };
  },
);

const md = createMarkItDown();
md.registerConverter(myConverter);

CLI

# Convert a file to Markdown
markitdown document.pdf

# Write output to a file
markitdown document.pdf -o output.md

# Structured JSON output
markitdown document.pdf --json

# Batch conversion
markitdown file1.docx file2.xlsx

# Pipe from stdin
cat document.pdf | markitdown

Exit codes: 0 success, 1 conversion failure, 2 bad arguments, 3 file not found, 4 permission denied, 5 unsupported format.

Set MARKITDOWN_OUTPUT_FORMAT=json or MARKITDOWN_QUIET=1 as environment variable alternatives to --json and --quiet.

Development

# Install dependencies
bun install

# Run tests
bun test

# Type check
bun run typecheck

# Build
bun run build

# Compile standalone binary
bun run compile

Architecture

The library uses a composable functional pipeline instead of class-based converters:

• Matchers decide if a converter handles the input: byMime(), byExt(), byUrl(), anyOf(), allOf(), hasCharset()
• Transform steps process data: async (ctx) => Promise<ConvertResult>
• converter() combines a name, matcher, and transform into a Converter

Converters are registered with priorities. Specific format converters (DOCX, PDF, etc.) are tried first, generic ones (plain text, HTML) are tried last.

License

Apache 2.0 — see LICENSE.

Acknowledgments

This is a TypeScript port of Microsoft's markitdown Python library. Test fixtures are from the original project.