[Guides](/safe-docx/guides.md) / Convert DOCX to Markdown

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) | Yes | No (external CLI) | No (JS library) |
| Headings, lists, links, bold/italic | Yes | Yes | Yes |
| GitHub-flavored tables | Yes (lossy on merged cells) | Yes | Limited |
| Footnotes | Yes (`[^n]`) | Yes | No |
| Extra runtime to install | None (npx) | pandoc binary | Node project |
| Also edits the .docx in place | Yes (separate tools) | No | No |

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](/comparisons/safe-docx-vs-python-docx.md).

## The workflow, step by step

1.  1
    
    ### Install safe-docx for your agent
    
    safe-docx is an Apache-2.0-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

### [Convert DOCX to HTML](/safe-docx/guides/convert-docx-to-html.md)

### [Convert DOCX to PDF](/safe-docx/guides/convert-docx-to-pdf.md)

## Frequently asked questions

<details>
<summary>Can safe-docx convert a DOCX file to Markdown?</summary>

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.
</details>

<details>
<summary>Is the DOCX-to-Markdown conversion lossy?</summary>

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.
</details>

<details>
<summary>Can I convert Markdown back into the original DOCX?</summary>

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.
</details>

<details>
<summary>Which agents can run the conversion?</summary>

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.
</details>

## 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](/products/safe-docx.md) [Browse templates](https://openagreements.org/templates)