docx-md-comments

docx-md-comments is a DOCX to Markdown converter and Markdown to DOCX converter focused on one hard problem: preserving Microsoft Word comments through roundtrip edits.

It is built for workflows where you:

1. start with a Word .docx containing comments
2. edit content and comments in Markdown (manually or with an LLM)
3. convert back to Word without losing comment structure

LLM-focused benefit:

• LLMs can draft or rewrite content
• LLMs can add new comments and threaded replies in Markdown
• those comments/replies are reconstructed as native Word comment threads on export

At A Glance

Why This Is Useful

Most generic converters drop or flatten comment metadata. This project is focused on Word review workflows, so comments remain usable after conversion.

Common use cases:

• legal, scientific, or editorial review drafts with heavy comment threading
• LLM-assisted editing where the model also writes comments/replies for reviewers
• roundtrip pipelines where Word comments must survive intact

Before You Start

Requirements:

• Python 3.10+
• Pandoc installed and available on PATH

Install Pandoc:

• macOS: brew install pandoc
• Ubuntu/Debian: sudo apt-get install pandoc
• Windows (PowerShell): choco install pandoc -y

Install

Recommended (pipx, isolated app install):

pipx install docx-md-comments

Alternative (pip):

python -m pip install docx-md-comments

Installed commands:

• dmc
• docx-comments
• docx2md / d2m
• md2docx / m2d

Update To Latest Version

If installed with pipx:

pipx upgrade docx-md-comments

If installed with pip:

python -m pip install --upgrade docx-md-comments

Quick Start

Convert Word to Markdown:

dmc draft.docx

Creates draft.md.

Convert Markdown back to Word:

dmc draft.md

Creates draft.docx.

LLM Editing Workflow

1. Convert reviewed Word document to Markdown:

dmc reviewed.docx

2. Edit reviewed.md manually or with an LLM. The LLM can update prose and add root comments or threaded replies.
3. Convert back to Word:

dmc reviewed.md

4. Open reviewed.docx in Word and continue normal comment-based review.

Command Variants

DOCX -> Markdown:

docx-comments draft.docx
docx2md draft.docx
d2m draft.docx

Markdown -> DOCX:

md2docx draft.md
m2d draft.md

Explicit input/output paths

DOCX -> Markdown:

docx2md draft.docx -o draft.md
d2m draft.docx -o draft.md
dmc docx2md draft.docx -o draft.md

Markdown -> DOCX:

md2docx draft.md -o draft.docx
m2d draft.md -o draft.docx
dmc md2docx draft.md -o draft.docx

Use a reference Word document for styling:

md2docx draft.md --ref original.docx -o final.docx
m2d draft.md -r original.docx -o final.docx

--ref maps to Pandoc --reference-doc.

Pass-through Pandoc arguments (advanced)

Unknown flags are passed through to Pandoc:

docx2md draft.docx -o draft.md --extract-media=media
dmc md2docx draft.md --reference-doc=template.docx

Limitations

• Tracked Changes: Word revisions are not preserved through roundtrip. Resolve them in Word first.
• Formatting: This project prioritizes comment fidelity. Very complex layouts may not roundtrip perfectly.

Help

dmc --help
docx2md --help
md2docx --help

For Contributors: Testing

Run full suite:

make test

Roundtrip-focused tests only:

make test-roundtrip

make test also writes:

• artifacts/out_test.md
• artifacts/out_test.docx

Report Issues

Please open bugs/feature requests at:

https://github.com/Pascal-Kueng/docx-md-comments/issues

When reporting a conversion bug, include:

• input sample (or minimal repro)
• command used
• expected vs actual behavior (Word view)
• failing failure_bundle path if tests failed

Technical Notes (Brief)

• Marker style uses ///C<ID>.START/// / ///C<ID>.END/// (optional ==...== wrapper).
• Reply relationships are reconstructed as native Word threads (commentsExtended.xml paraIdParent + story markers).
• Validation fails fast on malformed marker edits with line-specific diagnostics.

For maintainer details, see AGENTS.md.