How to Convert DOCX Files to Markdown on Mac (No Dependencies)

You have a folder of Word documents. You need them in Markdown - for a docs site, a Git repository, an AI pipeline, or just because Markdown is a better format for text that needs to last. The conversion should be simple. It usually isn’t.

Why DOCX to Markdown Is Harder Than It Looks

Word documents store content as XML wrapped in a ZIP archive. What looks like a clean document in Word is actually a complex tree of paragraph styles, run properties, relationship references, and embedded objects. Converting this to Markdown means:

• Mapping heading styles correctly. Word uses Heading 1 through Heading 9 styles, but also allows manual formatting that looks like a heading but isn’t one. Good converters use the style data. Bad ones guess from font size.
• Preserving table structure. Markdown tables are pipe-delimited grids. Word tables can have merged cells, nested tables, variable column widths, and cell-level formatting. Not all of this translates.
• Handling lists reliably. Numbered lists in Word have complex continuation logic. A list that restarts at “1” versus one that continues from a previous section depends on internal numbering definitions, not visible formatting.
• Dealing with images. Images in DOCX are embedded binary objects. They need to be extracted, saved as files, and referenced in the Markdown output.

The result: most “quick” conversion methods produce Markdown that needs significant cleanup.

Method 1: Pandoc (Free, Requires Terminal)

Pandoc is the standard CLI tool for document conversion. It handles DOCX to Markdown well if you’re comfortable with the terminal.

Install:

brew install pandoc

Basic conversion:

pandoc document.docx -t markdown -o document.md

With image extraction:

pandoc document.docx -t markdown --extract-media=./images -o document.md

Batch conversion (all DOCX files in a folder):

for f in *.docx; do
  pandoc "$f" -t markdown --extract-media=./media -o "${f%.docx}.md"
done

What works well: - Heading hierarchy, bold, italic, links - Numbered and bullet lists - Basic tables - Image extraction with proper references - Footnotes and citations

Where it falls short: - Complex tables with merged cells produce broken Markdown - Custom Word styles (beyond standard headings) get ignored - Track changes and comments are lost - No OCR - if the DOCX contains embedded scanned images, you get the image file but not the text in it - Every team member needs Pandoc installed and configured

Pandoc is the right choice for developers who live in the terminal and need a scriptable, repeatable pipeline.

Method 2: MarkItDown (Free, Requires Python)

MarkItDown is Microsoft’s open-source Python tool, built specifically for converting documents to Markdown for LLM workflows.

Install:

pip install markitdown

Usage:

markitdown document.docx > document.md

Strengths: - Designed for AI/LLM preprocessing - Handles DOCX, PDF, PPTX, XLSX, HTML, and images - Actively maintained by Microsoft

Weaknesses: - Requires Python 3.10+ and pip - No built-in batch processing UI - No OCR for scanned documents - Output can be inconsistent with complex formatting

Good for developers building data pipelines who already have Python in their toolchain.

Method 3: Online Converters (Free, Privacy Risk)

Sites like word2md.com and docstomarkdown.pro let you paste or upload Word content and get Markdown back.

Pros: - Zero installation - Works from any browser - Fine for quick one-off conversions of public content

Cons: - Your document content goes to a third-party server - Paste-based tools lose images, tables, and complex formatting - Upload-based tools work better but still have privacy implications - No batch processing - Not automatable

If you’re converting a public README or a blog draft, online tools are fine. For contracts, internal documentation, client work, or anything with sensitive content, they’re a non-starter.

Method 4: File2Text (Mac App, Zero Dependencies)

If you want the conversion quality of Pandoc without the terminal, or the convenience of online tools without the privacy trade-off, File2Text fills that gap.

How it works:

1. Drag your DOCX files (or an entire folder) onto the app
2. Choose Markdown or plain text output
3. Get structured output with headings, tables, lists, and formatting preserved

What sets it apart:

• No dependencies. No Homebrew, no Python, no terminal. Install from the Mac App Store and go.
• Built-in OCR. If your Word document contains scanned images or embedded PDFs, the OCR engine extracts the text. Pandoc and MarkItDown skip this entirely.
• Watch Folder. Point it at a directory and every new file dropped in gets converted automatically. This is the answer to the “how do I automate DOCX-to-Markdown in my workflow” question without writing scripts.
• Finder Quick Action. Right-click any DOCX file in Finder, select “Convert to Markdown.” No need to open the app.
• Smart document detection. The app recognizes different document types (reports, invoices, agreements) and applies extraction rules tailored to each structure.
• 50+ formats. Not just DOCX. PDF, PPTX, EPUB, MOBI, XLSX, images, JSON, YAML, and more - all in one app.

Everything processes locally on your Mac. No uploads, no accounts, no internet connection required.

For a broader comparison of Markdown conversion tools, see the Best File to Markdown Converter for Mac (2026) guide.

Automating DOCX-to-Markdown Workflows

The original question that inspired this post came from someone trying to convert DOCX to Markdown inside an automation pipeline. Here are the practical approaches:

For script-based automation (CI/CD, cron jobs):

Pandoc in a shell script is the standard. Wrap it in a Makefile or CI step:

# Convert all Word docs in /input to Markdown in /output
find ./input -name "*.docx" -exec sh -c '
  pandoc "$1" -t markdown --extract-media=./media \
    -o "./output/$(basename "$1" .docx).md"
' _ {} \;

For folder-based automation (no coding):

File2Text’s Watch Folder does this without scripts. Set a watched directory, and any DOCX file dropped in gets converted to Markdown automatically. This integrates with tools like Hazel, folder actions, or any workflow that outputs files to a directory.

For Python-based pipelines:

MarkItDown integrates directly into Python scripts:

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.docx")
print(result.text_content)

Tips and Edge Cases

Clean your Word document first. If the source DOCX has inconsistent heading styles (manual bold + large font instead of actual Heading styles), every converter will struggle. Apply proper styles in Word before converting.

Watch out for track changes. Most converters process the accepted version of the document. If you need track changes preserved, accept or reject them before converting.

Tables with merged cells will break. Markdown tables don’t support cell merging. Any converter will either flatten merged cells or produce invalid Markdown. For complex tables, consider converting to HTML tables within your Markdown.

Embedded fonts and colors are lost. Markdown doesn’t support custom fonts or text colors. If your document relies on color-coded content, you’ll need to find another way to represent that information.

Test with one file first. Before batch converting 200 documents, convert one representative file and review the output carefully. Catch formatting issues early so you can adjust settings or clean source files before processing the whole batch.

Check your Markdown flavor. Pandoc supports multiple Markdown dialects (strict, GitHub-flavored, CommonMark). If your output destination expects a specific flavor, configure the converter accordingly. For Pandoc, use -t gfm for GitHub-flavored Markdown.