@mdgate/converters

Real-world files to Markdown, in pure TypeScript.

@mdgate/converters is the complete deterministic reader: one toMarkdown(bytes) for PDF, Word, Excel, PowerPoint, OpenDocument, Apple iWork, HWP, WPS, email, OneNote, Visio, ebooks, archives, and more.

Works in Node.js, Cloudflare Workers, Edge runtimes, and browsers.

No Python. No native addons. No WASM. No third-party runtime dependencies.

npm install @mdgate/converters

import { toMarkdown } from '@mdgate/converters';

const markdown = await toMarkdown(bytes, {
  path: 'report.docx',
});

The input is bytes. The output is Markdown.

Convert a file in your browser. Full docs live in the repository README.

Why @mdgate/converters

A JavaScript application that needs to read real-world files quickly becomes a collection of unrelated parsers.

This package puts them behind one interface:

Uint8Array → Markdown

toMarkdown is create(all()). all() registers every converter that needs no configuration. Raster images, audio, and video need callbacks, so they are exported but not included in all().

One format

If your application only needs one format, install only that converter.

npm install @mdgate/pdf

import { toMarkdown } from '@mdgate/pdf';

const markdown = await toMarkdown(bytes);

Your own set

import { create } from '@mdgate/core';
import { pdf } from '@mdgate/pdf';
import { docx } from '@mdgate/docx';
import { xlsx } from '@mdgate/xlsx';

const read = create([
  pdf(),
  docx(),
  xlsx(),
]);

Or start from all() and add media callbacks:

import { all, create, image } from '@mdgate/converters';
import { ai } from '@mdgate/ai';

const media = ai({
  baseURL: 'https://api.example.com/v1',
  apiKey: process.env.API_KEY!,
  model: 'your-model',
});

const read = create([
  ...all(),
  image(media.convertImage),
]);

Node.js

import { readFile } from 'node:fs/promises';
import { toMarkdown } from '@mdgate/converters';

const bytes = new Uint8Array(await readFile('report.docx'));
const markdown = await toMarkdown(bytes, {
  path: 'report.docx',
});

The optional path is a format hint. The converter never reads that path from disk.

Cloudflare Workers and Edge runtimes

import { toMarkdown } from '@mdgate/converters';

export default {
  async fetch(request: Request) {
    const bytes = new Uint8Array(await request.arrayBuffer());
    const markdown = await toMarkdown(bytes, {
      path: request.headers.get('x-filename') ?? undefined,
    });

    return new Response(markdown, {
      headers: {
        'content-type': 'text/markdown; charset=utf-8',
      },
    });
  },
};

Browser

import { toMarkdown } from '@mdgate/converters';

const file = input.files![0];
const bytes = new Uint8Array(await file.arrayBuffer());

const markdown = await toMarkdown(bytes, {
  path: file.name,
});

Try it in your browser

Packages

| Package | Handles | |---|---| | @mdgate/converters | Bundle: every deterministic format below, toMarkdown, all() | | @mdgate/docx | docx, docm | | @mdgate/doc | doc (binary Word) | | @mdgate/rtf | rtf | | @mdgate/pptx | pptx, pptm, ppsx, ppsm | | @mdgate/ppt | ppt, pps, pot (binary PowerPoint) | | @mdgate/xlsx | xlsx, xlsm, xlsb, xls | | @mdgate/csv | csv | | @mdgate/text | txt, md, and source files | | @mdgate/data | json, jsonl, xml, yaml | | @mdgate/subtitle | srt, vtt, webvtt, ass, lrc, sub, sbv, ttml, jss | | @mdgate/html | html, htm, html4, html5, xhtml, mhtml, mht | | @mdgate/email | eml, msg, mbox, emlx | | @mdgate/ipynb | ipynb (Jupyter) | | @mdgate/odf | odt, ods, odp, odg | | @mdgate/pages | pages | | @mdgate/numbers | numbers | | @mdgate/keynote | key | | @mdgate/epub | epub, ibooks | | @mdgate/pdf | pdf | | @mdgate/fb2 | fb2, fb2.zip | | @mdgate/mobi | mobi, azw, azw3, prc | | @mdgate/latex | tex, latex, ltx | | @mdgate/visio | vsd, vsdx, vss, vst, vssx, vstx | | @mdgate/onenote | one, onetoc2, onepkg | | @mdgate/hwp | hwp, hwpx, hwt, hwtx | | @mdgate/wps | wps, wpt, et, ett, dps, dpt | | @mdgate/zip | zip, zipx, jar | | @mdgate/image | jpeg*, png*, webp*, gif*, tiff*, heic*, bmp*, svg, svgz | | @mdgate/audio | mp3*, wav*, m4a*, aac*, ogg*, flac*, weba* | | @mdgate/video | mp4*, m4v*, mov*, webm*, mkv*, avi* |

* Needs a callback: vision for raster images (image()), transcription for audio (audio()), video understanding for video(). Not registered by all(). SVG converts locally.

@mdgate/converters is the complete reader in the open-source mdgate/converters project.

For AI agents, the same converter architecture can be used to extend read_file from text files to real-world document formats.

License

MIT