Skip to main content
Beginner ⏱ 10 min

Convert DOCX to Markdown with an AI agent

Turn an existing Word .docx into clean Markdown with safe-docx and an AI agent — headings, lists, links, tables, and footnotes preserved. Step-by-step.

Getting clean Markdown out of a Word document usually means reaching for pandoc, scripting python-docx paragraph by paragraph, or unzipping the OOXML and parsing document.xml by hand. Those work, but they live outside your agent and need their own runtime. If you already drive an AI coding agent, safe-docx exposes a single export tool that does the conversion in-session — no extra toolchain, and document content never leaves your machine.

How DOCX-to-Markdown options compare

Capability safe-docx export pandoc mammoth.js
Runs inside your AI agent (MCP)YesNo (external CLI)No (JS library)
Headings, lists, links, bold/italicYesYesYes
GitHub-flavored tablesYes (lossy on merged cells)YesLimited
FootnotesYes ([^n])YesNo
Extra runtime to installNone (npx)pandoc binaryNode project
Also edits the .docx in placeYes (separate tools)NoNo

safe-docx export is one-way and lossy by design. For a feature-by-feature breakdown of the editing surface, see safe-docx vs python-docx.

The workflow, step by step

  1. 1

    Install safe-docx for your agent

    safe-docx is an MIT-licensed MCP server that runs locally via npx. Add it to your agent once. For Claude Code:

    claude mcp add safe-docx -- npx -y @usejunior/safe-docx

    It works the same way with Gemini CLI, Cursor, and Codex — any MCP-compatible client.

  2. 2

    Get a .docx to convert

    Use a document you already have, or download a real contract template to follow along. Save it next to your project, for example bonterms-mutual-nda.docx.

  3. 3

    Ask the agent to export it to Markdown

    Tell your agent in plain language: “Export bonterms-mutual-nda.docx to Markdown.” Under the hood the agent calls the safe-docx export tool with the Markdown format:

    export(file_path="bonterms-mutual-nda.docx", format="markdown")

    Markdown is the default format, so export(file_path="bonterms-mutual-nda.docx") does the same thing. The tool writes bonterms-mutual-nda.md next to the source and returns its path, byte count, and the rendered Markdown.

  4. 4

    Review the Markdown output

    The emitter walks the document's structure: headings become #..######, bold and italic runs become **bold** and *italic*, hyperlinks become Markdown links, numbered and bulleted lists keep their nesting, tables become GitHub-flavored Markdown tables, and footnotes become [^n] references. A converted heading and clause look like this:

    ## 1. Confidential Information

"Confidential Information" means any **non-public** information disclosed by one
party to the other, whether disclosed [in writing](https://example.com) or orally.
  5. 5

    Know what export does and doesn't do

    Export is intentionally lossy and one-way: it produces a clean textual rendering, not a round-trippable copy. Merged table cells flatten, and equations, text boxes, charts, and absolute page layout are not represented. There is no Markdown-to-DOCX reverse step — to change the Word file itself, use safe-docx's in-place editing tools (replace_text, insert_paragraph) instead.

Related guides

Conversion & Export · 10 min

Convert DOCX to HTML

Render a Word .docx to semantic HTML (paragraphs, headings, lists, tables, images) with the safe-docx export tool — ready for previews, web rendering, and content extraction.

Read the guide →

Frequently asked questions

Can safe-docx convert a DOCX file to Markdown?

Yes. The export tool renders an open .docx to Markdown when you pass format markdown (the default). It preserves headings, bold and italic, links, lists, GitHub-flavored tables, and footnotes.

Is the DOCX-to-Markdown conversion lossy?

Yes, intentionally. Export is a one-way, semantic rendering — not a round-trip. Merged table cells flatten, and equations, text boxes, charts, and exact page layout are not represented.

Can I convert Markdown back into the original DOCX?

No. There is no reverse step. safe-docx edits existing .docx files in place with tools like replace_text and insert_paragraph, so you change the Word document directly rather than rebuilding it from Markdown.

Which agents can run the conversion?

Any MCP-compatible client — Claude Code, Gemini CLI, Cursor, and Codex — once safe-docx is installed. It runs locally via npx, so document content stays on your machine.

Convert and edit DOCX from your agent

Install safe-docx, point your agent at a Word file, and export it to Markdown — or edit it in place.

About safe-docx Browse templates