Markdown Them

Convert various document files into Markdown (.md) from a web application, an Electron desktop app, a VS Code extension, or a Node.js package.

• Web App: Client-side only document converter running entirely in your browser. Hosted and deployed directly on GitHub Pages.

• Desktop App: A premium Electron application for converting local files, folders, and text inputs with custom output directory options. Available for Windows (Portable), Linux (.AppImage, .deb), and macOS (.dmg).

• VS Code Extension: Right-click context menus in the file explorer and side-by-side Markdown previews for developer workflows.

• Node.js Package: Integrate the same converter engine in your custom scripts, CLIs, and automations.

• Supported formats: .docx, .pdf, .html, .xlsx, .pptx, .odt, .odp, .ods, .rtf.

• Concurrent batch processing: Convert dozens of files at once with optimized performance.

Markdown Them Variants

Markdown Them comes in four variants so you can use the same converter wherever it fits your workflow:

Web and Desktop Apps

This repo includes a shared React UI for a local-only web app and an Electron desktop app.

• Web app: Client-side conversion only. It accepts multiple files or text input and does not send files to a server. Deployed to GitHub Pages.
• Desktop app: Electron shell with custom window controls. It accepts text input, one or many files, and multiple folders. File conversions write sibling .md files next to the originals.

Local app commands:

npm run start:web
npm run start:desktop
npm run preview:desktop

Build-only commands:

npm run build:web
npm run build:desktop
npm run build:apps

Desktop Packaging Pipeline:

Build production-ready installers and binaries (Windows Portable .exe, Linux .AppImage/.deb, macOS .dmg) via electron-builder:

# Build for Windows (Portable exe)
npm run dist:desktop:win

# Build for Linux (AppImage & deb)
npm run dist:desktop:linux

# Build for macOS (dmg)
npm run dist:desktop:mac

# Build for all platforms
npm run dist:desktop:all

The resulting binaries will be placed in the dist/installers directory.

VS Code Extension

Usage

1. Convert Multiple Files (Batch)

1. In the Explorer side bar, select one or more files.
2. Right-click and choose Convert to Markdown.
3. Files will be converted concurrently (up to the defined limit). You'll see notifications as each file completes.

2. Convert Active File

• While viewing a document, press Ctrl+M Ctrl+D (or Cmd+M Ctrl+D on Mac).
• A markdown preview will open in a new pane beside your current editor.

3. Change Concurrency Limit

• Use the command palette (Ctrl+Shift+P) and search for Markdown Them: Set Max Concurrent Conversions.
• Or, go to File > Preferences > Settings and search for Markdown Them.

[!NOTE] .pptx, .odt, and .odp conversion extracts structured text plus main content images as inline Base64 data URIs where available. Backgrounds, repeated logos, and small decorative icons are filtered to keep Markdown readable. .ods extracts sheets as Markdown tables, and .rtf preserves common text styling, headings, and bullets.

4. Troubleshooting

If a file fails to convert, you can view detailed error logs and stack traces by opening the Developer: Toggle Developer Tools command (from the Command Palette) and checking the Console tab.

Configuration

You can change this in three ways:

1. Command Palette — Run Markdown Them: Set Max Concurrent Conversions (Ctrl+Shift+P) to get an interactive input box pre-filled with the current value.

2. Settings UI — Open Settings (Ctrl+,) and search for Markdown Them.

3. settings.json — Add the key directly:

{
  // Convert up to 4 files at the same time
  "markdown-them.maxConcurrentConversions": 4
}

Node.js Package

Starting with v1.2.0, the shared converter is also packaged for Node.js consumers as @the-long-ride/markdown-them:

npm i @the-long-ride/markdown-them
pnpm add @the-long-ride/markdown-them

import { convertFileToMarkdown, generateMarkdown } from "@the-long-ride/markdown-them";

const outputPath = await convertFileToMarkdown("./docs/report.docx");
const markdown = await generateMarkdown("./docs/report.docx");

Local build commands:

npm run pack:vsix
npm run pack:node-package

Tag releases publish the Node.js package to npm after the package artifact is built. Configure this GitHub repository secret before pushing a v* tag:

NPM_TOKEN

Source Layout

• src/core: Shared document-to-Markdown conversion logic.
• src/app: Shared React UI and browser-only conversion adapter.
• src/electron: Electron main/preload process for the desktop app.
• src/shared: Shared format metadata and filename helpers.
• src/vscode: VS Code command registrations and editor integration.
• src/nodejs-package: Node.js package entry point.
• scripts: App build and local startup scripts.
• nodejs-package: Publishable npm package metadata, README, license, and generated dist.

Safely Powered By

I care about security & licensing for commercial use, so I picked popular packages with permissive open-source or standard licenses. Special thanks to the authors and contributors of these incredible libraries that power this project:

• react / react-dom (MIT License): Interactive interface structure.
• gsap / @gsap/react (GreenSock Standard License): Premium page transition animations.
• lucide-react (ISC License): Elegant UI icons.
• mammoth (BSD-2-Clause License): Robust conversion of .docx documents.
• @opendocsg/pdf2md (MIT License): Reliable text extraction from .pdf files.
• jszip (MIT or GPL-3.0 License): Zip extraction of files.
• fast-xml-parser (MIT License): Lightweight XML parsing for Office documents.
• turndown (MIT License): Clean conversion of HTML content to Markdown.
• officeparser (MIT License): Fallback text extractor for unusual Office formats.

Credits & Links

VS Code Marketplace | Open VSX | GitHub Repository | Changelog | Contribution Guidelines

License

MIT (with Theme Usage Restriction)