word-to-markdown

word-to-markdown

An Anthropic Agent Skill for converting Word documents (.docx) to Markdown — with a unique ability to convert MathType equations to inline LaTeX.

🎯 Core Problem

Academic and educational Word documents use MathType (公式编辑器) to embed thousands of mathematical equations. These equations are stored as OLE binary objects inside the .docx file, using a proprietary binary format called MTEF (MathType Equation Format).

When you try to convert these documents to Markdown, every existing tool fails:

The root cause: these tools only handle modern Word OMML equations (Word 2007+ native). They have zero support for MathType's OLE/MTEF binary format, which is still widely used in Chinese textbooks, academic papers, and legacy documents.

This tool solves the problem

We directly parse the MTEF binary data from OLE objects and translate the formula syntax tree into LaTeX:

oleObject.bin (binary) → MTEF Parser → Syntax Tree → $ LaTeX $

Before (pandoc output — equations are broken image links):

一般地，对于两个集合![](media/image59.wmf)，![](media/image60.wmf)，
如果集合![](media/image59.wmf)中任意一个元素都是集合![](media/image60.wmf)中的元素，
记作![](media/image61.wmf)(或![](media/image62.wmf))

After (this tool — equations are readable LaTeX):

一般地，对于两个集合$ A $，$ B $，
如果集合$ A $中任意一个元素都是集合$ B $中的元素，
记作$ A⊆B $(或$ B⊇A $)

🔧 Technical Approach

Why is this hard?

1. .docx is a ZIP archive containing XML + binary files
2. MathType equations are embedded as OLE Compound Document binary objects (oleObject*.bin)
3. Inside each OLE object is MTEF data — a proprietary binary format with byte-level record structures (CHAR, TMPL, LINE, PILE, MATRIX, EMBELL, etc.)
4. The relationship between oleObject*.bin and image*.wmf is defined in word/_rels/document.xml.rels and word/document.xml

What we do

┌──────────────┐                    ┌───────────────────┐
│   .docx      │───── unzip ──────→ │ oleObject*.bin     │
│   (ZIP)      │                    │ (MathType OLE)     │
└──────┬───────┘                    └─────────┬─────────┘
       │                                      │
       │                              OLE Parser + MTEF Parser
       │                                      │
       │                                      ▼
       │                            ┌───────────────────┐
       │  pandoc                    │  LaTeX formulas    │
       │                            │  $ \frac{1}{2} $   │
       ▼                            └─────────┬─────────┘
┌──────────────┐                              │
│  Markdown    │                              │
│  with        │◄──── regex replace ──────────┘
│  ![](*.wmf)  │     (image ref → LaTeX)
└──────────────┘
       │
       ▼
┌──────────────┐
│  Final .md   │
│  with LaTeX  │
└──────────────┘

Key steps:

1. pandoc converts the docx to basic Markdown (text structure preserved, equations become ![](media/image*.wmf))
2. Unzip the docx to extract all oleObject*.bin files
3. Parse document.xml to build the mapping: image*.wmf ↔ oleObject*.bin
4. For each OLE object: parse OLE compound document → extract MTEF stream → parse binary records → build syntax tree → translate to LaTeX
5. Replace ![](media/image*.wmf) in the Markdown with the corresponding $ LaTeX $

📦 Installation

git clone https://github.com/Wonderptg/word-to-markdown.git

Prerequisites

• Python 3.7+ (no pip packages needed — MTEF parser is fully self-contained)
• pandoc for initial docx → Markdown conversion

# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt install pandoc

🚀 Usage

Quick Start

python scripts/convert.py --docx your_document.docx

Output: your_document_latex.md

All Options

python scripts/convert.py --docx input.docx              # auto pandoc + convert
python scripts/convert.py --docx input.docx -v            # show progress
python scripts/convert.py --docx input.docx -o output.md  # custom output path
python scripts/convert.py --docx input.docx --input existing.md  # skip pandoc step
python scripts/convert.py --docx input.docx --timeout 5   # 5s timeout per equation

As an Anthropic Agent Skill

Copy the project to your skills directory:

cp -r word-to-markdown ~/.claude/skills/

Then ask Claude: "把这个 Word 文档转成 Markdown，里面的公式要转成 LaTeX"

📊 Performance

Tested on a real-world 23MB Chinese math textbook (18 chapters, 420+ pages):

📁 Project Structure

word-to-markdown/
├── SKILL.md                          # Anthropic Agent Skill definition
├── README.md
├── LICENSE                           # Apache 2.0
├── .gitignore
└── scripts/
    ├── convert.py                    # Main CLI tool
    └── mtef_parser/                  # MTEF binary parser (self-contained)
        ├── mtef.py                   # MTEF parser & LaTeX translator
        ├── record.py                 # Record type definitions
        ├── chars.py                  # Character mapping tables (hex → LaTeX)
        └── ole_util/                 # OLE Compound Document reader
            ├── ole.py                # OLE file parser
            ├── header.py             # OLE header parser
            ├── helper.py             # Byte conversion utilities
            ├── sector.py             # Sector reader
            ├── dir.py                # Directory entry parser
            ├── stream.py             # Stream definitions
            └── stream_reader.py      # Stream data reader

⚠️ Limitations

• Only handles MathType OLE equations (the older embedding method). Modern Word OMML equations are already handled by pandoc natively.
• ~2% of complex/malformed equations may fail to parse — they are kept as image references as fallback.
• Uses a 2-second timeout per equation to skip any malformed OLE objects that cause the parser to hang.
• Non-equation images (diagrams, charts, screenshots) are preserved as-is.
• Runs on macOS/Linux only (uses SIGALRM for timeout).

🙏 Acknowledgments

• MTEF-py by AndyQsmart — MTEF binary format parser (bundled in scripts/mtef_parser/)
• Anthropic Skills — Agent skill specification

License

Apache License 2.0