Markdown to Word (DOCX) Converter

pandoc (required):

# macOS
brew install pandoc

# Linux (Debian/Ubuntu)
sudo apt-get install pandoc

# Windows
choco install pandoc

python-docx (required for template creation):

pip install python-docx

Verify pandoc installation:

pandoc --version

Instructions

When the user requests to convert a Markdown file to Word format:

1. Check if pandoc is installed by running pandoc --version

   • If not installed, guide the user to install it (see Requirements section)

2. Identify the input and output files

   • Ask for clarification if the user hasn't specified the output filename
   • Use meaningful names (e.g., if input is report.md, suggest report.docx)

3. Run the conversion script using the Bash tool:

   python .claude/skills/md-to-docx/convert_md_to_docx.py input.md output.docx
   

4. Use additional options as needed:

   • Add --toc for table of contents (default: no TOC)
   • Add --no-chinese-template if user doesn't want FangSong font
   • Add --no-superscript-citations to disable automatic citation superscript conversion
   • Add --reference-doc template.docx for custom styling
   • Add --title, --author, --date for document metadata

5. For batch conversions:

   python .claude/skills/md-to-docx/convert_md_to_docx.py --batch input_dir/ output_dir/
   

6. Verify the conversion succeeded and inform the user of the output location

Default behavior: The script automatically uses a Chinese template with FangSong (仿宋) font for Chinese text unless --no-chinese-template is specified.

Examples

Convert a single file (uses default Chinese template):

python .claude/skills/md-to-docx/convert_md_to_docx.py "教育改革方案.md" "教育改革方案.docx"

Convert with table of contents (optional, default is no TOC):

python .claude/skills/md-to-docx/convert_md_to_docx.py report.md report.docx --toc

Convert with metadata:

python .claude/skills/md-to-docx/convert_md_to_docx.py paper.md paper.docx \
  --title "研究报告" \
  --author "张三" \
  --date "2025-11-20"

Batch convert all markdown files:

python .claude/skills/md-to-docx/convert_md_to_docx.py --batch ./markdown_files/ ./word_docs/

Use custom template for organizational styling:

python .claude/skills/md-to-docx/convert_md_to_docx.py doc.md doc.docx \
  --reference-doc company_template.docx

Supporting Files

This Skill includes additional resources:

• README.md: Detailed usage guide with examples
• 快速使用指南.md: Quick start guide in Chinese
• convert_md_to_docx.py: Main conversion script with automatic post-processing
• create_chinese_template.py: Utility to create custom Chinese templates
• fix_heading_fonts.py: Post-processing script for font and spacing fixes
• chinese_template.docx: Default Chinese font template (FangSong, 1.5x line spacing, heading spacing)

Troubleshooting

"pandoc: command not found"

• Install pandoc using your package manager (see Requirements section)

Images not appearing in output

• Ensure image paths in markdown are correct (use relative paths from markdown file location)
• Verify image files exist at specified paths

Table formatting issues

• Verify markdown table syntax:

  | Header 1 | Header 2 |
  |----------|----------|
  | Cell 1   | Cell 2   |
  

Script execution errors

• Ensure script has execute permissions: chmod +x convert_md_to_docx.py
• Use forward slashes in all file paths (Unix style)

Chinese Document Best Practices

When converting Chinese documents:

1. Encoding: Ensure markdown files use UTF-8 encoding
2. Punctuation: Use proper Chinese punctuation (。，""（）；！？)
3. Font: Default template uses FangSong for all Chinese text (body, headings, and subtitles) with black color
4. Line spacing: 1.5x line spacing for all paragraphs (符合中文文档标准)
5. Paragraph formatting: First-line indent of two characters (24pt, precisely aligned) for proper Chinese document style
6. Heading spacing: 1 line (12pt) spacing after all headings for better readability
7. Heading style: All headings use FangSong font without italic style
8. Custom templates: Create organizational templates with create_chinese_template.py

Command Line Options Reference

Default Document Formatting

The Chinese template automatically applies:

• Font: FangSong (仿宋) for Chinese text, Times New Roman for English
• Font size: 12pt (body text)
• Font color: Black for all text
• Line spacing: 1.5x for all paragraphs
• First-line indent: 24pt (2 Chinese characters)
• Heading spacing: 12pt (1 line) after each heading
• Heading style: Bold, no italic
• Citation superscript: Numbers before sentence-ending punctuation (。；) are automatically converted to superscript (e.g., 参考文献1。 → 参考文献¹。). Only converts numbers 1-60 that directly follow Chinese characters or letters.
• Table of contents: Not generated by default (use --toc to add)

For complete documentation, see README.md.