# docx-to-markdown

**Repository Path**: DaFei_93/docx-to-markdown

## Basic Information

- **Project Name**: docx-to-markdown
- **Description**: Convert Word documents with MathType/Equation Editor formulas to clean Markdown. 自研 MTEF 解析器，输出即合格。MathType/Equation Editor 公式转 LaTeX，docx→md 零人工干预。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# docx-to-markdown

Convert Word documents (.docx / legacy .doc) containing **MathType / Equation Editor formulas** to clean, knowledge-base-ready Markdown. 输出即合格、零人工干预。

- **MathType OLE formulas (MTEF v5 + v3 old formats)** → LaTeX, via a built-in binary parser — no Mathpix, no OCR, no cloud, no cost
- **Word native OMML formulas** → LaTeX via markitdown 0.1.7
- **Preview-image fallback**: formulas that cannot be parsed are kept as images — content never silently lost
- **Legacy .doc** auto-converted via LibreOffice (preferred) or Word COM (Windows), with post-conversion OLE integrity checks
- **15+ automated cleanup rules** + regression-gate scanner + four-bucket reconciliation: the report does not lie

## Install

```bash
pip install docx-to-markdown
```

Requires Python >= 3.10. The command is `docx2markdown` (not `docx2md` — that name is taken by an unrelated package).

## Usage

```bash
docx2markdown input.docx                # -> input/README.md + input/images/
docx2markdown input.docx -o /path/dir   # custom output directory
docx2markdown input.docx --no-images    # text-only mode
docx2markdown --version
```

Batch mode (multiple inputs): `docx2markdown a.docx b.docx -o out/`

Each conversion writes `_转换报告.md` with formula statistics, four-bucket reconciliation, and an audit trail (`audit/failures.json`). Exit code is 0 only when everything is clean.

## Optional runtime tools (not required for install)

| Capability | Tool | Notes |
|---|---|---|
| Legacy `.doc` conversion | LibreOffice (`soffice`) **or** Microsoft Word (COM, Windows) | LibreOffice preferred — embeds old OLE without corruption |
| WMF/EMF preview rendering | Windows GDI+ (built-in, `assets/wmf2png.ps1`) **or** ImageMagick | Last-resort fallback for unparseable formulas |

Missing `olefile` in script-direct mode degrades `.doc` pre-scanning with an explicit warning.

## Formula pipeline

```
.docx
 ├─ MathType OLE (MTEF v5)  -> built-in parser (mtef_package) -> LaTeX
 ├─ MathType OLE (MTEF v3)  -> mathtypejx-derived byte layer   -> LaTeX
 ├─ OMML                    -> markitdown 0.1.7                -> LaTeX
 ├─ unparseable OLE         -> preview image fallback (WMF/EMF -> PNG)
 └─ legacy .doc             -> LibreOffice / Word COM -> .docx -> pipeline above
```

Then 15+ deterministic cleanup rules (spacing shells, escaped subscripts, fragment merges, `\neq`, `\times`, etc.) + four-bucket reconciliation + regression gate scanner. Output is verified, not just produced.

## Relationship to this skill

This package is the **open-source fork** of the author's `docx-to-markdown` WorkBuddy skill (private). The skill remains the authoritative source; this CLI is synced from it by `tools/sync_to_cli.py` (patch manifest + fail-loud assertions + test gate). See `NOTICE` for third-party attribution.

## License

MIT — see [LICENSE](LICENSE). Third-party attribution in [NOTICE](NOTICE).