Markdown to Word Document Skill

Overview

Convert Markdown documents to Word documents that comply with Chinese typesetting standards. Supports full Markdown syntax and automatically applies professional formatting settings.

Dependency Requirements

Python Dependencies

bash

pip install python-docx Pillow beautifulsoup4 PyYAML

Optional Dependencies

bash

npm install -g @mermaid-js/mermaid-cli   # Mermaid diagram rendering
brew install librsvg                       # SVG→PNG (recommended, rsvg-convert)
# or pip install cairosvg                  # SVG→PNG alternative
# or npm install puppeteer                 # SVG→PNG alternative (scripts/svg2png.js)

Inline
<svg>...</svg>
blocks in the content will be automatically rendered as PNG and embedded. The rendering priority is rsvg-convert → cairosvg → svg2png.js(puppeteer); any one of the three is sufficient. If none are available, it will fall back to displaying the SVG source code in a code block.

Quick Start

Main conversion script:

scripts/md2word.py

bash

# Basic conversion
python scripts/md2word.py input.md output.docx

# Use preset format
python scripts/md2word.py input.md --preset=academic

# Use custom configuration
python scripts/md2word.py input.md --config=my-config.yaml

# Footnote/endnote mode (default footnote is page footnote; endnote=end-of-document notes + superscript numbering)
python scripts/md2word.py input.md --notes=endnote

# Book merging: multiple chapter md files → single docx (table of contents + chapter division by input files + header, specify output with -o)
python scripts/md2word.py --book ch01.md ch02.md ch03.md -o book.docx --preset=book-publish

--book
only converts the boundaries between adjacent input files into new sections. Markdown horizontal lines
---
,
***
,
___
in chapter content will be retained as horizontal lines in both single-chapter and book modes, and do not bear pagination or chapter division semantics.

--book
will resolve local relative image paths according to the directory where each chapter's Markdown is located before merging, then write to a temporary merged draft. Both Markdown images and HTML
<img src>
are supported; HTTP/HTTPS, data URI, anchors and absolute paths remain unchanged. The image resolution process for single-chapter conversion remains the same.

The
book-publish
preset by default starts a new page for Markdown titles whose text is exactly "Chapter Summary" or "Hands-on Practice"; the converter writes Word native
pageBreakBefore
in the title paragraph itself, without inserting empty paragraphs, pagination runs or new sections. This rule also applies to single-chapter conversion, and is disabled by default in other presets; it can be overridden via
pagination.page_break_before_headings
.

When the same
[^label]
appears repeatedly in the content, the native
footnote
mode will generate independent Word footnotes for each occurrence and repeat the same definition text, ensuring that the footnote can be seen at each reference position; the
endnote
mode still reuses the same number and one endnote definition.

In native
footnote
mode, when two footnote markers are directly adjacent in the source code, the output will add a 9pt superscript NBSP between the two superscripts; no additional space is added if there is already a space or punctuation in the source code. Page footnote paragraphs are fixed to 0 before/after spacing and single auto line spacing; these two rules do not apply to
endnote
.

Page footnotes can be used in both regular content and Markdown blockquotes (
>
);
[^label]
in blockquotes will generate native Word footnote references, not remain as literal markers in the content, while retaining the blockquote paragraph and inline formats like bold.

All Markdown blockquotes read a set of
quote
configuration uniformly, and are not diverted by text labels such as "Chapter Guide" or "Case". The built-in preset's quote box and fenced code block share the neutral light gray visual token
#F5F5F5
, with the style of full-width content paragraph shading without visible borders; no table container is used, so Word's "View Gridlines" will not show dashed outer borders. Text retains left/right and top/bottom padding via
padding
; empty quote lines inside generate
paragraph_spacing
exact empty paragraphs with the same background color, so multi-paragraph callouts maintain a single continuous gray background. Consecutive empty quote lines inside are deterministically collapsed into one, and leading/trailing empty quote lines are ignored.

Inline code prioritizes protecting backtick ranges: Markdown markers like
_
and
*
within are retained as literals, and will not be combined with adjacent code segments to form italics or bold; for example,
`law_keyword`
will be fully output as a single code run.

Underscores in regular technical identifiers are retained as literals: names like
payment_instance_id
and
API_SERVER_KEY
in content and Markdown tables will not be interpreted as italics or bold. Underscore emphasis must be at word boundaries; explicit
_italic_
,
__bold__
and
___bold-italic___
are still rendered according to their original semantics.

All fenced code blocks (including
text
,
markdown
and language-less fences) follow the existing monospaced, compact code content style; you can adjust only the vertical spacing between the entire block and the preceding/following content via
code_block.content.space_before
and
space_after
.

Markdown tables are fixed within the available width of the page content; multi-column long headers will automatically wrap, and the converter will unify the total table width, grid column width and cell width to prevent the table from crossing the left/right margins.

Both Markdown and HTML data tables append a fixed-height blank space (default 6pt exact) via
table.space_after
by the table component itself; subsequent content maintains the regular content's 1.5x line spacing and 0 before-paragraph spacing. Images and captions do not use this table blank space.

Regular Markdown table captions (such as
**Table 10-5: Title**
) will be automatically centered horizontally and have first-line indentation removed; explicit
<div align="center">...</div>
can still be used. The original font size and boldness of the caption are not affected by automatic alignment.

Configuration System

Built-in Presets

Preset information is dynamically read from YAML files. Run the following command to view the complete list:

bash

python scripts/config.py --list

Common presets:

legal — Legal document format (default)
service-plan — Legal service plan (with hierarchical color scheme)
minimal — Minimalist format
academic — Academic paper format
report — Work report format
book-publish — Chinese book publishing format (content in Songti, titles in Heiti, TOC/header with book title, used with
```
--book
```
for book merging export)

Complete configurations are in
assets/presets/*.yaml
, and design instructions are in
assets/theme-notes/

Custom Configuration

Copy the configuration template and modify it:

bash

cp assets/config-template.yaml my-config.yaml

Word Template Files

Place

.docx

templates in the

assets/templates/

directory, or specify using

--template

Word Template vs Configuration File:

Word Template: Controls visual elements (header, footer, Logo)
Configuration File: Controls format parameters (font size, line spacing, margins)

Reference Documents

Configuration Reference: references/config-reference.md
Style Mappings: references/style-mappings.md
Usage Examples: references/examples.md

Required Permissions and Security Notes

This skill calls local scripts to perform document conversion, involving the following capability boundaries. Please be aware before use:

Local Code Execution

```
scripts/md2word.py
```
calls external rendering tools via
```
subprocess.run
```
to render diagrams and SVG:
- Mermaid Diagrams: Calls
```
mmdc
```
  (MMDCCMD environment variable →
```
node_modules/.bin/mmdc
```
  in the same directory as the script → system PATH), only renders user-input mermaid code, and commands are spliced as parameter arrays without shell string splicing.
- SVG Rendering: Calls
```
rsvg-convert
```
  →
```
cairosvg
```
  →
```
node scripts/svg2png.js
```
  (Puppeteer) according to priority. When inline SVG is untrusted input, it may trigger renderer parsing issues or resource consumption. Please only convert documents from trusted sources.

Network Access (Enabled by Default)

When converting Markdown containing external URL images, it will automatically initiate requests to any HTTP/HTTPS address (via
```
urllib.request
```
, timeout 20s) to download images for embedding into Word.
This is the default behavior: external images will be downloaded and embedded normally; if download fails, it falls back to a text placeholder.
Please be aware of the risks: processing untrusted Markdown may trigger SSRF (accessing internal network addresses), leak metadata such as the converter's IP/time to third parties, or introduce malicious or oversized image loads. Please only convert documents from trusted sources.
The above download requests do not upload document content, only pull images according to the image URLs in the Markdown.

Environment Variable Reading

```
chart_handler.py
```
reads the
```
MMDCCMD
```
environment variable to locate the mermaid-cli executable (optional; if not set, it falls back to the script's same-directory node_modules and system PATH).

File Access

Reads user-specified Markdown input files, Word templates in
```
assets/templates/
```
and YAML configurations in
```
assets/presets/
```
.
Generates Word documents in the output directory (the
```
--book
```
mode generates a temporary merged Markdown file, which is automatically deleted after conversion; local relative images in chapters are first relocated according to their respective source file directories).

Error Handling

File Encoding: Automatically detects UTF-8 and GBK
Template Not Found: Creates a new document using default format
Mermaid Failure: Falls back to text description
Overly Large Images: Automatically compresses and adjusts size

Directory Structure

md2word/
├── SKILL.md               # This document
├── CHANGELOG.md           # Version history
├── references/            # Reference documents
│   ├── config-reference.md
│   ├── style-mappings.md
│   └── examples.md
├── scripts/               # Conversion scripts
│   ├── md2word.py         # Main script
│   ├── config.py          # Configuration module (includes --list to view presets)
│   ├── extract_template_config.py  # Extract configuration from Word template
│   ├── formatter.py       # Text formatting module
│   ├── table_handler.py   # Table processing module
│   └── chart_handler.py   # Diagram rendering module
└── assets/                # Resource files
    ├── presets/           # YAML preset configurations
    ├── theme-notes/       # Preset design documentation
    ├── templates/         # Word template files
    └── config-template.yaml

md2word

NPX Install

Tags

SKILL.md Content (Chinese)

Markdown to Word Document Skill

Overview

Dependency Requirements

Python Dependencies

Optional Dependencies

Quick Start

Configuration System

Built-in Presets

Custom Configuration

Word Template Files

Reference Documents

Required Permissions and Security Notes

Local Code Execution

Network Access (Enabled by Default)

Environment Variable Reading

File Access

Error Handling

Directory Structure