{"id":"25cf9795-d57d-42d0-9f36-a2b27202eb2c","slug":"word-to-markdown","kind":"skill","name":"word-to-markdown","summary":"","owner":"Wonderptg","repoUrl":"https://github.com/Wonderptg/word-to-markdown","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-03-04T07:15:13.000Z","addedAt":"2026-10-22T00:41:02.283Z","logoUrl":"https://avatars.githubusercontent.com/u/203843619?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T09:17:14.878Z","sample":false,"url":"https://conduits.dev/tools/word-to-markdown","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# word-to-markdown\n\nAn [Anthropic Agent Skill](https://github.com/anthropics/skills) for converting Word documents (`.docx`) to Markdown — with a unique ability to **convert MathType equations to inline LaTeX**.\n\n## 🎯 Core Problem\n\nAcademic 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).\n\nWhen you try to convert these documents to Markdown, **every existing tool fails**:\n\n| Tool | What happens to MathType equations |\n|------|-----------------------------------|\n| **pandoc** | Exports as `.wmf` image placeholders → `![](media/image59.wmf)` — **unreadable** |\n| **eqword2llm** | Silently drops all equations → **formulas disappear** |\n| **LibreOffice** | Loses equation formatting → **broken output** |\n| **Online converters** | Can't parse OLE objects → **same `.wmf` images** |\n\n**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.\n\n### This tool solves the problem\n\nWe directly parse the **MTEF binary data** from OLE objects and translate the formula syntax tree into LaTeX:\n\n```\noleObject.bin (binary) → MTEF Parser → Syntax Tree → $ LaTeX $\n```\n\n**Before** (pandoc output — equations are broken image links):\n```markdown\n一般地，对于两个集合![](media/image59.wmf)，![](media/image60.wmf)，\n如果集合![](media/image59.wmf)中任意一个元素都是集合![](media/image60.wmf)中的元素，\n记作![](media/image61.wmf)(或![](media/image62.wmf))\n```\n\n**After** (this tool — equations are readable LaTeX):\n```markdown\n一般地，对于两个集合$ A $，$ B $，\n如果集合$ A $中任意一个元素都是集合$ B $中的元素，\n记作$ A⊆B $(或$ B⊇A $)\n```\n\n## 🔧 Technical Approach\n\n### Why is this hard?\n\n1. `.docx` is a ZIP archive containing XML + binary files\n2. MathType equations are embedded as **OLE Compound Document** binary objects (`oleObject*.bin`)\n3. Inside each OLE object is **MTEF** data — a proprietary binary format with byte-level record structures (CHAR, TMPL, LINE, PILE, MATRIX, EMBELL, etc.)\n4. The relationship between `oleObject*.bin` and `image*.wmf` is defined in `word/_rels/document.xml.rels` and `word/document.xml`\n\n### What we do\n\n```\n┌──────────────┐                    ┌───────────────────┐\n│   .docx      │───── unzip ──────→ │ oleObject*.bin     │\n│   (ZIP)      │                    │ (MathType OLE)     │\n└──────┬───────┘                    └─────────┬─────────┘\n       │                                      │\n       │                              OLE Parser + MTEF Parser\n       │                                      │\n       │                                      ▼\n       │                            ┌───────────────────┐\n       │  pandoc                    │  LaTeX formulas    │\n       │                            │  $ \\frac{1}{2} $   │\n       ▼                            └─────────┬─────────┘\n┌──────────────┐                              │\n│  Markdown    │                              │\n│  with        │◄──── regex replace ──────────┘\n│  ![](*.wmf)  │     (image ref → LaTeX)\n└──────────────┘\n       │\n       ▼\n┌──────────────┐\n│  Final .md   │\n│  with LaTeX  │\n└──────────────┘\n```\n\n**Key steps:**\n1. **pandoc** converts the docx to basic Markdown (text structure preserved, equations become `![](media/image*.wmf)`)\n2. **Unzip** the docx to extract all `oleObject*.bin` files\n3. **Parse** `document.xml` to build the mapping: `image*.wmf` ↔ `oleObject*.bin`\n4. **For each OLE object**: parse OLE compound document → extract MTEF stream → parse binary records → build syntax tree → translate to LaTeX\n5. **Replace** `![](media/image*.wmf)` in the Markdown with the corresponding `$ LaTeX $`\n\n## 📦 Installation\n\n```bash\ngit clone https://github.com/Wonderptg/word-to-markdown.git\n```\n\n### Prerequisites\n\n- **Python 3.7+** (no pip packages needed — MTEF parser is fully self-contained)\n- **pandoc** for initial docx → Markdown conversion\n\n```bash\n# macOS\nbrew install pandoc\n\n# Ubuntu/Debian\nsudo apt install pandoc\n```\n\n## 🚀 Usage\n\n### Quick Start\n\n```bash\npython scripts/convert.py --docx your_document.docx\n```\n\nOutput: `your_document_latex.md`\n\n### All Options\n\n```bash\npython scripts/convert.py --docx input.docx              # auto pandoc + convert\npython scripts/convert.py --docx input.docx -v            # show progress\npython scripts/convert.py --docx input.docx -o output.md  # custom output path\npython scripts/convert.py --docx input.docx --input existing.md  # skip pandoc step\npython scripts/convert.py --docx input.docx --timeout 5   # 5s timeout per equation\n```\n\n### As an Anthropic Agent Skill\n\nCopy the project to your skills directory:\n\n```bash\ncp -r word-to-markdown ~/.claude/skills/\n```\n\nThen ask Claude: *\"把这个 Word 文档转成 Markdown，里面的公式要转成 LaTeX\"*\n\n## 📊 Performance\n\nTested on a real-world 23MB Chinese math textbook (18 chapters, 420+ pages):\n\n| Metric | Value |\n|--------|-------|\n| Total MathType equations | 7,025 |\n| Successfully converted to LaTeX | 6,877 (**97.9%**) |\n| Image references replaced in Markdown | 10,972 |\n| Failed / timed out (kept as image fallback) | 148 (2.1%) |\n| Total conversion time | ~3 minutes |\n\n## 📁 Project Structure\n\n```\nword-to-markdown/\n├── SKILL.md                          # Anthropic Agent Skill definition\n├── README.md\n├── LICENSE                           # Apache 2.0\n├── .gitignore\n└── scripts/\n    ├── convert.py                    # Main CLI tool\n    └── mtef_parser/                  # MTEF binary parser (self-contained)\n        ├── mtef.py                   # MTEF parser & LaTeX translator\n        ├── record.py                 # Record type definitions\n        ├── chars.py                  # Character mapping tables (hex → LaTeX)\n        └── ole_util/                 # OLE Compound Document reader\n            ├── ole.py                # OLE file parser\n            ├── header.py             # OLE header parser\n            ├── helper.py             # Byte conversion utilities\n            ├── sector.py             # Sector reader\n            ├── dir.py                # Directory entry parser\n            ├── stream.py             # Stream definitions\n            └── stream_reader.py      # Stream data reader\n```\n\n## ⚠️ Limitations\n\n- Only handles **MathType OLE** equations (the older embedding method). Modern Word OMML equations are already handled by pandoc natively.\n- ~2% of complex/malformed equations may fail to parse — they are kept as image references as fallback.\n- Uses a 2-second timeout per equation to skip any malformed OLE objects that cause the parser to hang.\n- Non-equation images (diagrams, charts, screenshots) are preserved as-is.\n- Runs on macOS/Linux only (uses `SIGALRM` for timeout).\n\n## 🙏 Acknowledgments\n\n- **[MTEF-py](https://github.com/AndyQsmart/MTEF-py)** by AndyQsmart — MTEF binary format parser (bundled in `scripts/mtef_parser/`)\n- **[Anthropic Skills](https://github.com/anthropics/skills)** — Agent skill specification\n\n## License\n\n[Apache License 2.0](LICENSE)\n"}