Skip to content

Commit d848a8d

Browse files
committed
feat: add md-to-docx-plus skill with LaTeX equation support
Add a new skill that converts Markdown to Word (.docx) with editable OMML math equations. Unlike the existing md-to-docx skill (JavaScript), this uses Python (python-docx + latex2word + latex2mathml) to convert LaTeX math expressions ($inline$ and $$display$$) into native Word equations that are fully editable in Word's equation editor. Supports: fractions, subscripts, superscripts, roots, summations, integrals, matrices, Greek letters, limits, and more.
1 parent 0f4adc2 commit d848a8d

3 files changed

Lines changed: 793 additions & 0 deletions

File tree

skills/md-to-docx-plus/SKILL.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
name: md-to-docx-plus
3+
description: "Convert Markdown files to Word (.docx) with editable OMML math equations. Handles LaTeX formulas ($...$ and $$...$$), producing natively editable equations in Word. Use this skill whenever converting markdown to docx where the content contains math formulas, equations, scientific notation, or LaTeX expressions — even if the user just says 'convert this md to docx' and the file might contain math."
4+
---
5+
6+
# Markdown to Word (.docx) with Editable Equations
7+
8+
Convert Markdown (`.md`) files into professionally formatted Word (`.docx`) documents with **editable OMML equations** derived from LaTeX math notation. Uses Python (`python-docx` + `latex2word` + `latex2mathml`) — no Pandoc, LibreOffice, or MS Office required.
9+
10+
The key difference from `md-to-docx`: LaTeX math expressions (`$inline$` and `$$display$$`) are converted into **native Word OMML equations** that are fully editable in Word's equation editor — not images, not plain text.
11+
12+
## How to Convert
13+
14+
```bash
15+
# Install dependencies (one-time)
16+
pip install python-docx latex2word latex2mathml lxml
17+
18+
# Convert (run from workspace root)
19+
python3 skills/md-to-docx-plus/scripts/md_to_docx_plus.py <input.md> [output.docx]
20+
```
21+
22+
If `output.docx` is omitted, it defaults to `<input-basename>.docx`.
23+
24+
## Skill Folder Contents
25+
26+
| File | Purpose |
27+
|------|---------|
28+
| `SKILL.md` | This instruction file |
29+
| `scripts/md_to_docx_plus.py` | Python Markdown-to-Word converter with equation support |
30+
| `scripts/requirements.txt` | Python dependencies |
31+
32+
## Prerequisites
33+
34+
| Requirement | Version | Notes |
35+
|-------------|---------|-------|
36+
| **Python** | 3.10+ | Required runtime |
37+
| **python-docx** | 1.1+ | Word document generation |
38+
| **latex2word** | 1.0+ | LaTeX to OMML conversion |
39+
| **latex2mathml** | 3.77+ | LaTeX to MathML (used by latex2word) |
40+
| **lxml** | 5.0+ | XML processing |
41+
42+
Works on Windows, macOS, and Linux. No system-level installs beyond Python packages.
43+
44+
## Features
45+
46+
The converter:
47+
48+
- **Converts LaTeX math to editable Word equations**`$inline$` and `$$display$$` notation becomes native OMML
49+
- **Extracts YAML front-matter** — uses `title`, `date`, `version`, `audience` for the title page
50+
- **Generates a title page** — with project name, subtitle, date, version, and audience
51+
- **Generates a table of contents** — built from H1-H3 headings
52+
- **Embeds PNG images** — resolves `![alt](path)` references relative to the input `.md` file
53+
- **Styled output** — Calibri body, Cambria Math for equations, Consolas for code, colored headings
54+
- **Handles all Markdown elements** — headings, paragraphs, tables, code blocks, lists, images, links, horizontal rules
55+
56+
## LaTeX Math Support
57+
58+
Inline math uses single `$...$`:
59+
60+
```markdown
61+
The loss function $L = -\sum_{i} y_i \log(\hat{y}_i)$ measures cross-entropy.
62+
```
63+
64+
Display (block) math uses double `$$...$$`:
65+
66+
```markdown
67+
$$
68+
\theta_{t+1} = \theta_t - \alpha \nabla_\theta J(\theta)
69+
$$
70+
```
71+
72+
Both produce **editable OMML equations** in Word — click to edit, same as inserting an equation via Word's ribbon.
73+
74+
Supported LaTeX constructs: fractions, subscripts, superscripts, square roots, summations, integrals, matrices, piecewise functions, Greek letters, operators, limits, and more.
75+
76+
## Front-Matter Format
77+
78+
```yaml
79+
---
80+
title: Project Name — Project Summary
81+
date: 2025-01-15
82+
version: 1.0
83+
audience: Engineering Team
84+
---
85+
```
86+
87+
The title is split on `` or `` into main title and subtitle for the title page.

0 commit comments

Comments
 (0)