docx2md

docx2md-cli

High-fidelity Word (.docx) to Markdown converter. Built for documents where structure matters — normative texts, policies, technical specs, government docs.

Install

pip install docx2md-cli

For custom YAML frontmatter loading:

pip install "docx2md-cli[frontmatter]"

CLI Usage

# Basic conversion
docx2md input.docx

# Full-featured
docx2md input.docx -o output.md --extract-images images/ --skip-before-heading

# Agent-friendly (machine-readable)
docx2md input.docx --json-stats -q -o output.md

# Stdin/stdout piping
cat input.docx | docx2md - -o -

Flags

Flag	Description
-o PATH	Output path. Use - for stdout.
--extract-images DIR	Extract embedded images and link them in Markdown.
--skip-before-heading	Skip content before the first Word heading (cover pages, TOC).
--frontmatter FILE	Prepend custom YAML frontmatter from a file.
--no-frontmatter	Disable all frontmatter (auto and custom).
-q, --quiet	Suppress stats output.
--json-stats	Emit stats as JSON to stderr.

Python API

from docx2md_cli import convert

result = convert(
    "input.docx",            # str path, bytes, or BinaryIO
    output_path="output.md", # optional
    images_dir="images",     # optional
    skip_before_heading=True,
    no_frontmatter=False,
    print_stats=False,
)

# result is list-like (backward compatible) with extras
lines = result.lines          # list of Markdown lines
stats = result.stats          # dict with counts
json_str = result.as_json()   # JSON string of stats

Stats dict keys

lines, bytes, headings, table_rows, figures, bold, footnotes, refs, tables_inserted, tables_total, underlined, ordered_list_items, nested_items

What It Preserves (that others don't)

• Field-code references: [N] citation refs from Word's field code state machine
• Bibliography SDT: Extracts bibliography content controls as [^rN] definitions
• Vertical merge (vMerge): Grouped table rendering for merged cells
• Split table detection: Merges 1-row header + data table pairs
• Inline footnotes: At their original Word position, not end-of-document
• Numbered vs bullet lists: Reads numbering.xml directly, preserves nesting
• Image extraction: Embedded images with caption-derived filenames
• Multi-language captions: ES, EN, FR, DE, PT, IT