Markdown to DOCX Conversion

Overview

Convert Markdown files to Word (.docx) documents with preserved formatting. Supports single-file conversion and multi-file merge into one document.

Quick Decision Flow

User requests md → docx conversion
    │
    └─ python scripts/convert.py input.md -o output.docx [--toc]
           │
           ├─ pypandoc available? → pandoc engine (full quality)
           └─ pypandoc not found? → markdown-it-py + python-docx fallback

The script auto-selects the best available engine. No manual pandoc check needed.

Step 1: Run the conversion script

The bundled scripts/convert.py handles everything:

python scripts/convert.py input.md -o output.docx

It automatically uses pypandoc (bundled pandoc) for best quality, or falls back to markdown-it-py + python-docx if pypandoc is unavailable.

Step 2: Confirm Conversion Parameters

Before converting, confirm with the user (or infer from context):

For Chinese documents, the skill automatically applies sensible Chinese typography defaults.

Step 3: Convert

Single File Conversion (Pandoc)

pandoc input.md -o output.docx \
  --from markdown+autolink_bare_uris+task_lists \
  --metadata title="Document Title" \
  --toc --toc-depth=3 \
  --syntax-highlighting=tango

Key pandoc flags explained:

• --from markdown+autolink_bare_uris+task_lists — enables GitHub-Flavored Markdown extensions
• --toc --toc-depth=3 — generates a table of contents for headings level 1–3
• --syntax-highlighting=tango — syntax highlighting theme for code blocks
• --metadata lang="zh-CN" — add for Chinese documents (spellcheck/hyphenation)

For simple documents (fewer than 3 headings), omit --toc to avoid a nearly-empty TOC.

Single File Conversion (Python Fallback)

python scripts/convert.py input.md output.docx

With explicit options:

python scripts/convert.py input.md output.docx \
  --page-size A4 \
  --font "Arial" \
  --font-size 11 \
  --toc

Multi-File Merge (Pandoc)

When merging, each input file becomes a chapter/section. Pandoc concatenates content intelligently:

pandoc file1.md file2.md file3.md -o merged.docx \
  --from markdown+autolink_bare_uris+task_lists \
  --metadata title="Merged Document" \
  --toc --toc-depth=3 \
  --syntax-highlighting=tango

Important for merge: If each file has its own # Title (H1), the resulting document will have multiple H1 headings, which creates a natural chapter structure. The TOC will reflect this.

For better chapter separation, insert page breaks between files:

# Add page break markers between files
for f in file1.md file2.md file3.md; do
  cat "$f"
  echo -e "\n\\newpage\n"
done | pandoc -o merged.docx --toc

Multi-File Merge (Python Fallback)

python scripts/convert.py file1.md file2.md file3.md -o merged.docx --toc

The Python script automatically inserts page breaks between merged files.

Step 4: Validate Output

After conversion, verify the output:

# Check file size and basic structure
python scripts/office/unpack.py output.docx /tmp/docx_check/ 2>/dev/null && \
  echo "Valid DOCX structure" || echo "May need inspection"

If the validation script is unavailable, this is a basic sanity check:

python -c "from docx import Document; doc = Document('output.docx'); print(f'Paragraphs: {len(doc.paragraphs)}, Sections: {len(doc.sections)}')"

Common Scenarios

Scenario 1: README.md to README.docx

pandoc README.md -o README.docx --from markdown+autolink_bare_uris+task_lists

No TOC needed for a single-page README.

Scenario 2: Technical Report with Code Blocks

pandoc report.md -o report.docx \
  --from markdown+autolink_bare_uris+task_lists \
  --toc --toc-depth=3 \
  --syntax-highlighting=pygments \
  --metadata title="Technical Report"

Scenario 3: Merge Multiple Chapter Files

# Files: chapter-01.md, chapter-02.md, chapter-03.md
pandoc chapter-*.md -o book.docx \
  --from markdown+autolink_bare_uris+task_lists \
  --toc --toc-depth=2 \
  --metadata title="Complete Guide" \
  --metadata author="Author Name"

Scenario 4: Chinese Document with Proper Typography

pandoc document.md -o document.docx \
  --from markdown+autolink_bare_uris+task_lists \
  --metadata lang="zh-CN" \
  --toc --toc-depth=3

Post-Conversion Formatting

After generating the .docx file, if the user wants additional formatting (headers/footers, page numbers, custom styles), use the docx skill for post-processing. The docx skill can:

• Add headers, footers, and page numbers
• Customize fonts and paragraph styles
• Add a letterhead or cover page
• Adjust page margins and orientation
• Insert watermarks

Troubleshooting

Reference: Pandoc Markdown Extensions

Useful extensions to enable via --from markdown+EXTENSION:

Boo哥AI智写 · 联系 QQ邮箱：409966830@qq.com · 智写万象，标定未来