Convert DOCX, XLS, and PPTX to Markdown

TL;DR: One set of open-source tools turns your entire Office archive into Markdown — Word docs become clean text files, spreadsheets become readable tables, presentations become slides you can edit anywhere — so nothing is lost in translation.

The problem

Every .docx, .xls, and .pptx file in your archive is a blind spot — your computer can open it, but you can’t search through it the way you search a folder of text files. grep (a command that searches every file for a word or phrase and shows you what it finds) doesn’t work on binary formats. One company’s vault held 753 of them (see the case study). 753 files the AI couldn’t see until they were plain text.

Word documents are write-only memory — time to make them readable.

The solution: one convert CLI

The migration-toolkit ships a single command (runs in your terminal) — migration-toolkit/convert — that routes any Office file to the right converter and writes Markdown:

uv run convert policy.docx -o policy.md
uv run convert notes.doc   -o notes.md            # .doc → LibreOffice → pandoc
uv run convert leads.xls --summary -o leads.md     # structured summary
uv run convert data.xlsx --sheet "Sheet1"          # one sheet to stdout
uv run convert deck.pptx -o deck.md                # → Marp
uv run convert feedback.csv --limit 10             # first 10 rows to stdout

No format sniffing on your end. Hand it a file; get Markdown back — save it to a file with -o, or print it straight to your screen with no cleanup needed. For Word docs with embedded images, add --extract-media:

uv run convert policy.docx --extract-media ./images -o policy.md

This tells Pandoc to extract images into the ./images folder and reference them from the Markdown — useful for image-heavy docs like branded reports or annotated screenshots.

Getting started

Three commands and you’re running:

# 1. Clone the repo
git clone https://github.com/markdown-company/ai-native-migration-templates.git
cd migration-toolkit

Or just go to the GitHub repo, click the green “Code” button, select “Download ZIP”, unzip it, and open a terminal in the migration-toolkit folder. Same result.

# 2. Install uv (one-time)
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell as admin)
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 3. Convert any Office file — uv syncs deps automatically
uv run convert policy.docx -o policy.md

Add this to your migration plan: for each Office file the AI encounters, it runs uv run convert <file> -o <file>.md before reading. The original stays in the archive; the Markdown becomes the AI’s working copy. That’s the loop.

When to convert vs. keep

Markdown is plain text — it can’t express everything an Office file can. What breaks:

• Formulas, macros, and pivot tables (the computed result is static)
• Tracked changes and comments (pandoc drops them - but some markdown plugins support comments!)
• Word mail-merge fields (the merge codes are lost)
• Embedded fonts, smart art, and complex layouts
• Cell styling and conditional formatting in spreadsheets

Rule of thumb: keep everything in the archive during migration. After converting, spot-check that the Markdown contains all the information you need, then delete the originals from your working folder. After six months, purge any Office file that hasn’t been opened — the archive still has the original if you ever need it.

Not everything should become Markdown. The rule:

The principle: convert what the AI should read; keep alongside what only Excel can compute. The Markdown is the source of truth for search and reasoning — the original stays as a reference artifact.

Real examples

Two files, two paths, one CLI:

Legacy .doc → Markdown. A privacy policy trapped in an old Word format:

uv run convert "Privacy policy.doc" -o "Privacy Policy.md"

LibreOffice (a free, open-source office suite) converts the .doc to .docx in a temporary folder, then pandoc converts that to Markdown — you get a readable, searchable, AI-ready file.

Lead list → structured summary. A 400-row spreadsheet of prospects:

uv run convert "Client leads.xls" --summary --name "Client Leads" -o "Client Leads.md"

--summary emits row counts, column names, and the full table — plus a key-value list when the sheet is two columns wide. The AI now sees your entire pipeline in a single file.

Why it works

Conversion is not the migration — it’s the unlock. Once a file is Markdown, you can search through it (every word, instantly), compare versions side by side, link to specific sections, and AI can read it — all without any extra tools. You own the files, you own the access. The command-line tool does the mechanical work; you decide what to convert and what to keep.

The backends

Three engines, one door:

The dispatcher lives in convert; the Python scripts that do the actual conversion are migration-toolkit/src/convert_docx_to_md.py and migration-toolkit/src/convert_xls_to_md.py. Each run checks every dependency and points you at the install command if something’s missing — it never silently fails.

When you run uv run convert policy.docx -o policy.md, here’s what happens:

1. uv ensures all Python dependencies are installed
2. convert detects .docx and dispatches to convert_docx_to_md.py
3. That script invokes pandoc to do the actual format conversion
4. The result is written to policy.md

Same pipeline for all formats — each backend script handles its own conversion and dependency checks.

What’s next

Conversion is running. Make sure nothing gets lost: AI-Native Migration Guardrails — a safety check that proves every file made it through.

Plain text. Plain simple. By Charles Henri Gayot.