Word to Markdown

Clean Markdown from any .docx, with comments, tracked changes and list structure kept.

docparse contract.docx --convert contract.md

MarkItDown vs AILANG Parse for Word documents. Microsoft MarkItDown and AILANG Parse both turn Word files into Markdown for RAG, search and LLM prompts. MarkItDown returns the body text without comments or tracked changes, and flattens nested lists. AILANG Parse keeps them, along with merged table cells, headers and footers, so your model reads what the reviewers read. On the 33 Word files in the open OfficeDocBench, AILANG Parse scores 97.1% and MarkItDown 42.8%.

AILANG Parse reads the Office XML inside the .docx directly. No AI model is involved, so the same file always gives the same Markdown, it runs on a laptop with no GPU, and the document never leaves the machine.

MarkItDown vs AILANG Parse, same files

Three Word files from the public OfficeDocBench corpus, converted to Markdown by MarkItDown and by AILANG Parse. Both outputs are shown exactly as the tools printed them. Download a file and run both yourself.

MarkItDown 0.1.5
Here is some text.

Here is some more text.
AILANG Parse
**Author:** Jesse Rosenthal

Here is some text.

Here is the text to be moved.

> [move-to by Jesse Rosenthal on 2016-04-16T08:20:00Z] Here is the text to be moved.

Here is some more text.

> [move-from by Jesse Rosenthal on 2016-04-16T08:20:00Z] ~~Here is the text to be moved.~~

A paragraph moved during review is part of the current document. MarkItDown’s output does not contain it. AILANG Parse keeps it in its new place and records where it came from, who moved it and when.

MarkItDown 0.1.5
# Document with Comment Ranges

The project deadline is March 15 and we need to prepare.

The budget allocation needs to be reviewed by the finance team.

Please review the technical specification before the meeting.
AILANG Parse
**Author:** python-docx

# Document with Comment Ranges

The project deadline is March 15 and we need to prepare.

> deadline is March 15
>
> **Comment (Alice Smith, 2026-03-01T10:00:00Z):** This deadline seems too tight

The budget allocation needs to be reviewed by the finance team.

> budget allocation
>
> **Comment (Bob Jones, 2026-03-02T14:30:00Z):** Need to increase by 15%

Please review the technical specification before the meeting.

> technical specification
>
> **Comment (Alice Smith, 2026-03-03T09:15:00Z):** Missing API section

Each comment comes through under the paragraph it belongs to, quoting the exact words it was attached to, with its author and date. Ask a model “what did finance object to?” and the answer is in the text it was given.

MarkItDown 0.1.5
# Project Requirements

* Frontend
* React components
* Button component
* Form component
* State management
* Backend
* API endpoints
* Database
* PostgreSQL schema
* Migrations
AILANG Parse
**Author:** python-docx

# Project Requirements

- Frontend
  - React components
    - Button component
    - Form component
  - State management
- Backend
  - API endpoints
  - Database
    - PostgreSQL schema
    - Migrations

The outline’s three levels stay three levels, so “Migrations” is still under Database, under Backend. Flattened, a list of requirements becomes a list of unrelated lines.

Outputs captured on 10 November 2026 with MarkItDown 0.1.5 (markitdown[docx]) and the AILANG Parse CLI, from the files linked above. The Timeline section after the lists is the same in both and is cut here.

Word file scores on an open benchmark

The examples above are three files. OfficeDocBench v2 scores every parser on the same 33 Word files. It checks headings, lists, tables, comments, tracked changes, notes, links and text against the source file. Scores on Word files:

AILANG Parse97.1%
Kreuzberg56.7%
Pandoc53.5%
Docling49.1%
Unstructured47.0%
LlamaParse43.7%
MarkItDown42.8%

The test files, the scoring code and the per-file results are public, so you can rerun the comparison or add your own files. Full tables, other formats and the method are on the benchmarks page.

What you get

In the Word fileIn the Markdown
Headings# to ######, at the level the document used.
Bold, italic, links**bold**, *italic* and [text](url) on the words that carried them.
Bulleted and numbered listsMarkdown lists, nested to the depth in the document.
TablesPipe tables. Merged cells are marked {colspan=N} or {merged} instead of shifting the columns.
CommentsA quote block under the paragraph: the commented words, then the author, date and comment.
Tracked changesThe current text, plus a note for each insertion, deletion or move with who made it and when. Deleted text is struck through.
Headers and footersKept once, labelled *Header:* and *Footer:*, including tables inside them.
Document propertiesThe author line at the top; the full metadata is in the JSON.
ImagesImage blocks in the JSON. Add --describe for AI-written image descriptions (opt-in).

Parsing without --convert (docparse contract.docx, or the folder command below) writes the Markdown together with a .json file. The JSON holds the same content as labelled blocks (heading, list with item levels, table with cell spans, comment, change), for pipelines that need structure rather than text. See DOCX Parsing for that output.

Run it

Install the CLI (it also sets up the AILANG runtime):

curl -fsSL https://www.sunholo.com/ailang-parse/install.sh | sh
# One file to Markdown
docparse contract.docx --convert contract.md

# A whole folder: one .md and one .json per file, compiled once
docparse ~/contracts/ --output-dir ~/contracts-md/

# Quarto Markdown instead, ready for `quarto render`
docparse contract.docx --convert contract.qmd

Point it at a folder and it converts every file in one run, which is far faster than a loop over single files. The Markdown is identical to running --convert on each file.

Over the API

The hosted API runs the same converter. POST /api/v1/convert with target=md returns the Markdown in the JSON response:

curl -s -X POST https://docparse.ailang.sunholo.com/api/v1/convert \
  -F "filepath=@contract.docx" \
  -F "target=md" \
  -F "apiKey=$DOCPARSE_API_KEY"

Or from Python (pip install ailang-parse):

from ailang_parse import DocParse

client = DocParse(api_key="dp_...")
print(client.convert_file("contract.docx", target="md").text)

Upload files up to 32 MB directly. Send larger files by URL. API keys, plan limits and the other ways to send a file are in the API reference.

Other output formats

Change the extension after --convert: .html, .qmd, .odt, or back to .docx in your own template with --reference-doc (see Document Generation). The same command converts .odt, .pptx, .xlsx, .html and .epub to Markdown too.

Most of your documents are PDFs? The same command converts them to Markdown on your machine: --pdf-backend poppler for PDFs that contain real text, --pdf-backend docling for scans. A PDF keeps less structure than a Word file, so where the .docx still exists, convert that. See PDF Parsing.

Frequently Asked Questions

How do I convert a DOCX file to Markdown?

docparse contract.docx --convert contract.md. For a whole folder, docparse ~/contracts/ --output-dir out/ writes one .md and one .json per file. Over the hosted API, POST the file to /api/v1/convert with target=md.

Does it keep comments and tracked changes?

Yes. Each comment is kept next to the words it is anchored to, with author and date. Insertions, deletions and moves are kept as marked revisions, so the Markdown shows the current text and what was changed in review.

Do I need a GPU or an AI model?

No. The .docx is read from its Office XML. The same file always gives the same Markdown, it runs offline, and nothing is sent anywhere. AI is only used if you ask for it with --describe or --summarize.

How does it compare with MarkItDown, Docling or Pandoc on Word files?

On the 33 Word files in the open OfficeDocBench v2, AILANG Parse scores 97.1%, against 56.7% for Kreuzberg, 53.5% for Pandoc, 49.1% for Docling and 42.8% for MarkItDown. The test files, scoring code and per-file results are public on the benchmarks page.

What about PDFs and scanned documents?

The same command converts PDFs, using a PDF reader on your machine: pdftotext or poppler for PDFs that contain real text, docling for scans. Where the original Word file exists, convert that instead. A PDF keeps less structure than the Word file it came from.