Markdown to Word (.docx) Converter
Convert Markdown files to professionally formatted Word documents, with automatic template style extraction and Mermaid diagram rendering.
How It Works
The bundled script (scripts/md_to_docx.py) handles the entire conversion:
- Parse Markdown into structured blocks (headings, body, lists, tables, code, quotes)
- Extract styles from an optional Word template (.doc or .docx) — font, size, alignment, spacing
- Apply formatting to each block, preserving inline Markdown (bold, italic, code, strikethrough)
- Render Mermaid diagrams to PNG via
mmdc (mermaid-cli) and embed them as images
- Output a ready-to-use .docx file
Dependencies
The script requires:
- python-docx:
pip install python-docx
- mmdc (for Mermaid rendering):
npm install -g @mermaid-js/mermaid-cli
- Chrome or Chromium: must be installed locally (auto-detected on macOS/Windows/Linux)
On macOS, .doc templates are converted via the built-in textutil. On Linux, LibreOffice is used as fallback.
Usage
Basic conversion (default Chinese typesetting)
python3 scripts/md_to_docx.py input.md -o output.docx
With template (auto-extract formatting)
python3 scripts/md_to_docx.py input.md -o output.docx -t template.doc
When Invoked as a Skill
When the user asks to convert a Markdown file to Word:
- Identify the input file — the user will typically specify a
.md file path
- Check for a template — ask if they have a
.doc/.docx template, or check if one exists in common locations (docs/, templates/)
- Ensure dependencies are installed:
pip3 install python-docx
npm list -g @mermaid-js/mermaid-cli 2>/dev/null || npm install -g @mermaid-js/mermaid-cli
- Run the script from the skill's
scripts/ directory:python3 <skill-path>/scripts/md_to_docx.py <input.md> -o <output.docx> [-t <template.doc>]
- Report results — tell the user the output path and whether all Mermaid diagrams rendered successfully
Template Format Detection
When a template is provided, the script analyzes it automatically:
- Title levels are identified by font size and alignment (largest centered = chapter title, etc.)
- Body text is identified by paragraphs with first-line indentation
- Page setup (margins, paper size) is copied from the template
- Chinese font pairing is preserved (e.g., Times New Roman ↔ 宋体, Arial ↔ 黑体)
If no template is provided, these defaults are used (Chinese publishing standard):
| Element |
Font |
Size |
Alignment |
| Chapter title (h1) |
黑体 |
18pt |
Center |
| Section title (h2) |
黑体 |
16pt |
Center |
| Subsection (h3) |
黑体 |
14pt |
Left |
| Body text |
宋体 |
10.5pt (五号) |
Justify, 2-char indent |
| Code |
Consolas |
9pt |
Left |
| Quote |
楷体 |
10.5pt |
Left indent, italic |
Supported Markdown Features
- Headings: h1–h6 (h1 = chapter, h2 = section, h3 = subsection, h4+ = sub-subsection)
- Body text with inline: bold, italic,
code, strikethrough, bold italic
- Bullet lists (
- or *) and ordered lists (1.)
- Tables with header detection
- Code blocks with language label
- Mermaid diagrams rendered to embedded PNG images
- Block quotes and horizontal rules
Mermaid Diagram Handling
Mermaid code blocks are rendered to PNG via mmdc using the local Chrome browser. If rendering fails (e.g., Chrome not found, syntax error), the diagram falls back to a code block display.
Common Mermaid compatibility fixes are applied automatically:
subgraph names containing colons are quoted- Parentheses in subgraph names are escaped
Cross-Platform Notes
- macOS: Chrome auto-detected at
/Applications/Google Chrome.app/...
- Windows: Checks
Program Files and LocalAppData
- Linux: Checks
/usr/bin/google-chrome, /usr/bin/chromium, /snap/bin/chromium
.doc conversion: Uses textutil on macOS, libreoffice on Linux
Limitations
- No support for footnotes, images, or links (Markdown image URLs are not fetched)
- Math equations (LaTeX) are preserved as plain text
- Nested lists deeper than one level are flattened
- Template detection works best with templates that have clear formatting differentiation between headings and body text
1---2name: md-to-docx3description: Convert Markdown files to formatted Word (.docx) documents with automatic template style detection. Use this skill whenever the user mentions converting Markdown to Word, exporting to .docx, generating a Word document from .md files, applying a Word template to Markdown content, or writing a book chapter to Word format. Also use when the user needs to handle Mermaid diagrams in Word documents, or wants Chinese typesetting conventions (宋体/黑体, 五号字, 首行缩进) applied to their output. Triggers on phrases like "转成 word", "导出 docx", "生成 Word 文档", "用模板排版", "Markdown to Word", "book to Word", "chapter to docx", or any request involving .md → .docx conversion.4---56# Markdown to Word (.docx) Converter78Convert Markdown files to professionally formatted Word documents, with automatic template style extraction and Mermaid diagram rendering.910## How It Works1112The bundled script (`scripts/md_to_docx.py`) handles the entire conversion:13141. **Parse Markdown** into structured blocks (headings, body, lists, tables, code, quotes)152. **Extract styles** from an optional Word template (.doc or .docx) — font, size, alignment, spacing163. **Apply formatting** to each block, preserving inline Markdown (bold, italic, code, strikethrough)174. **Render Mermaid diagrams** to PNG via `mmdc` (mermaid-cli) and embed them as images185. **Output** a ready-to-use .docx file1920## Dependencies2122The script requires:2324- **python-docx**: `pip install python-docx`25- **mmdc** (for Mermaid rendering): `npm install -g @mermaid-js/mermaid-cli`26- **Chrome or Chromium**: must be installed locally (auto-detected on macOS/Windows/Linux)2728On macOS, `.doc` templates are converted via the built-in `textutil`. On Linux, LibreOffice is used as fallback.2930## Usage3132### Basic conversion (default Chinese typesetting)3334```bash35python3 scripts/md_to_docx.py input.md -o output.docx36```3738### With template (auto-extract formatting)3940```bash41python3 scripts/md_to_docx.py input.md -o output.docx -t template.doc42```4344### When Invoked as a Skill4546When the user asks to convert a Markdown file to Word:47481. **Identify the input file** — the user will typically specify a `.md` file path492. **Check for a template** — ask if they have a `.doc`/`.docx` template, or check if one exists in common locations (`docs/`, `templates/`)503. **Ensure dependencies** are installed:51 ```bash52 pip3 install python-docx53 npm list -g @mermaid-js/mermaid-cli 2>/dev/null || npm install -g @mermaid-js/mermaid-cli54 ```554. **Run the script** from the skill's `scripts/` directory:56 ```bash57 python3 <skill-path>/scripts/md_to_docx.py <input.md> -o <output.docx> [-t <template.doc>]58 ```595. **Report results** — tell the user the output path and whether all Mermaid diagrams rendered successfully6061## Template Format Detection6263When a template is provided, the script analyzes it automatically:6465- **Title levels** are identified by font size and alignment (largest centered = chapter title, etc.)66- **Body text** is identified by paragraphs with first-line indentation67- **Page setup** (margins, paper size) is copied from the template68- **Chinese font pairing** is preserved (e.g., Times New Roman ↔ 宋体, Arial ↔ 黑体)6970If no template is provided, these defaults are used (Chinese publishing standard):7172| Element | Font | Size | Alignment |73|---------|------|------|-----------|74| Chapter title (h1) | 黑体 | 18pt | Center |75| Section title (h2) | 黑体 | 16pt | Center |76| Subsection (h3) | 黑体 | 14pt | Left |77| Body text | 宋体 | 10.5pt (五号) | Justify, 2-char indent |78| Code | Consolas | 9pt | Left |79| Quote | 楷体 | 10.5pt | Left indent, italic |8081## Supported Markdown Features8283- **Headings**: h1–h6 (h1 = chapter, h2 = section, h3 = subsection, h4+ = sub-subsection)84- **Body text** with inline: **bold**, *italic*, `code`, ~~strikethrough~~, ***bold italic***85- **Bullet lists** (`-` or `*`) and **ordered lists** (`1.`)86- **Tables** with header detection87- **Code blocks** with language label88- **Mermaid diagrams** rendered to embedded PNG images89- **Block quotes** and **horizontal rules**9091## Mermaid Diagram Handling9293Mermaid code blocks are rendered to PNG via `mmdc` using the local Chrome browser. If rendering fails (e.g., Chrome not found, syntax error), the diagram falls back to a code block display.9495Common Mermaid compatibility fixes are applied automatically:96- `subgraph` names containing colons are quoted97- Parentheses in subgraph names are escaped9899## Cross-Platform Notes100101- **macOS**: Chrome auto-detected at `/Applications/Google Chrome.app/...`102- **Windows**: Checks `Program Files` and `LocalAppData`103- **Linux**: Checks `/usr/bin/google-chrome`, `/usr/bin/chromium`, `/snap/bin/chromium`104- **`.doc` conversion**: Uses `textutil` on macOS, `libreoffice` on Linux105106## Limitations107108- No support for footnotes, images, or links (Markdown image URLs are not fetched)109- Math equations (LaTeX) are preserved as plain text110- Nested lists deeper than one level are flattened111- Template detection works best with templates that have clear formatting differentiation between headings and body text
Lord1Egypt