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:

1. Parse Markdown into structured blocks (headings, body, lists, tables, code, quotes)
2. Extract styles from an optional Word template (.doc or .docx) — font, size, alignment, spacing
3. Apply formatting to each block, preserving inline Markdown (bold, italic, code, strikethrough)
4. Render Mermaid diagrams to PNG via mmdc (mermaid-cli) and embed them as images
5. 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)#

bash

python3 scripts/md_to_docx.py input.md -o output.docx

With template (auto-extract formatting)#

bash

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:

1. Identify the input file — the user will typically specify a .md file path

2. Check for a template — ask if they have a .doc/ .docx template, or check if one exists in common locations ( docs/, templates/)

3. Ensure dependencies are installed: bash

   pip3 install python-docx
   npm list -g @mermaid-js/mermaid-cli 2>/dev/null || npm install -g @mermaid-js/mermaid-cli
   
   

4. Run the script from the skill's scripts/ directory: bash

   python3 <skill-path>/scripts/md_to_docx.py <input.md> -o <output.docx> [-t <template.doc>]
   
   

5. 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):

ElementFontSizeAlignmentChapter title (h1)黑体18ptCenterSection title (h2)黑体16ptCenterSubsection (h3)黑体14ptLeftBody text宋体10.5pt (五号)Justify, 2-char indentCodeConsolas9ptLeftQuote楷体10.5ptLeft 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