Md To Word

Markdown to Word Conversion

One command to professional Word documents — diagrams, tables, and formatting done right on first attempt.

Staleness Watch: Recheck external API and tool URLs before release or after upstream changes.

Convert any Markdown document into polished Word (.docx) files ready for stakeholders, executives, and external audiences. Supports all standard Markdown formatting, Mermaid diagrams (auto-converted to PNG), and SVG illustrations (auto-embedded).

Why Use This?

Document Publishing Workflow

Markdown (.md)  →  md-to-word.cjs  →  Word (.docx)  →  Final PDF
     ↓                   ↓                ↓               ↓
  Source            Automation      Manual polish     Distribution
  (your docs)      (this skill)    (page breaks,     (File > Save As)
                                    headers/footers)

1. Convert to Word: Run md-to-word.cjs — produces a complete, styled document
2. Optional polish: Add page breaks, headers/footers, custom branding
3. Export PDF: Word's File > Save As > PDF gives best fidelity

Supported Markdown Formatting

Mermaid Diagram Support

All Mermaid diagram types are supported:

Diagrams are rendered at 8x scale (2400px width) for crisp printing, then sized to fit within page bounds.

Quick Start

One-Command Conversion

# From your project root
node .github/muscles/md-to-word.cjs docs/spec.md

# With custom output name
node .github/muscles/md-to-word.cjs README.md output.docx

# Keep intermediate files for debugging
node .github/muscles/md-to-word.cjs docs/plan.md --keep-temp

What It Does

1. Preprocesses Markdown — fixes bullet lists, checkbox syntax, spacing
2. Converts Mermaid to PNG — renders diagrams with white backgrounds
3. Calculates optimal sizing — reads actual PNG dimensions, fits 90% of page
4. Converts SVG to PNG — handles banner images
5. Generates Word via pandoc — clean markdown-to-docx conversion
6. Formats tables — Microsoft blue headers, borders, alternating rows
7. Centers images — all diagrams centered on page
8. Styles headings — consistent colors and spacing

Installation

Prerequisites

Quick Install (All Dependencies)

macOS

brew install pandoc
npm install -g @mermaid-js/mermaid-cli svgexport

Windows

winget install JohnMacFarlane.Pandoc
npm install -g @mermaid-js/mermaid-cli svgexport

Options

Style Presets

# Academic paper with TOC
node md-to-word.cjs thesis.md --style academic --toc

# Professional report with cover
node md-to-word.cjs quarterly-report.md --style professional --cover --toc

SVG Image Handling

SVG files are automatically detected and converted to PNG for Word compatibility:

<!-- This SVG reference in your Markdown... -->
![Architecture](assets/architecture.svg)

<!-- ...becomes this embedded PNG in Word -->
![Architecture](images/architecture.png){width=5.8in}

Requirements: svgexport (npm install -g svgexport)

Best practices for SVG sources:

• Use viewBox for scalable graphics
• Embed fonts or use web-safe font stack
• Keep file size under 500KB for fast conversion
• Avoid external references (they won't resolve)

Image Sizing Algorithm

The script automatically fits images to page bounds:

Page: 8.5" × 11" (Letter)
Margins: 1" each side
Usable area: 6.5" × 9.0"
Max image: 6.5" × 3.6" (40% height for inline fit)

Algorithm Steps

1. Read PNG dimensions from file header (pure Node.js, no dependencies)
2. Calculate scale factors for width and height constraints
3. Apply most restrictive — ensures fit in both dimensions
4. Specify constraining dimension — pandoc preserves aspect ratio

Table Formatting

All tables receive professional OOXML styling:

Professional Features

Page Numbers

Centered page numbers in the footer, gray text (9pt).

Heading Hierarchy

• H1: Brand color, underline, 360/120 twip spacing
• H2: Secondary color, 280/80 twip spacing
• H3: Tertiary color, 240/80 twip spacing
• All headings: keepNext + keepLines (no orphans)

Code Blocks

• Font: Consolas 9pt
• Background: Light gray (#F5F5F5)
• Border: Left accent bar (#CCCCCC)
• Keep together: Won't split across pages

Hyperlinks

• Color: Microsoft blue (#0563C1)
• Style: Single underline
• Applied to both inline links and reference links

Captions

Paragraphs starting with "Table N" or "Figure N":

• Centered, italic, 9pt gray
• keepNext binding to following content

Troubleshooting

Debug Mode

node md-to-word.cjs doc.md --debug --keep-temp
# Check _debug_combined.md for preprocessed content
# Check images/ folder for generated PNGs

macOS Fallback (No Pandoc)

macOS ships textutil which can convert HTML to DOCX natively:

# Convert markdown to HTML first, then HTML to DOCX
npx marked document.md -o document.html
textutil -convert docx document.html -output document.docx

Limitations: textutil needs HTML input (not raw Markdown), produces simpler formatting, and doesn't support the table styling or image sizing that md-to-word.cjs provides. Use only when Pandoc is unavailable and a quick conversion is needed.

Batch Processing

Convert a Folder

# Windows PowerShell
Get-ChildItem docs/*.md | ForEach-Object {
    node .github/muscles/md-to-word.cjs $_.FullName --style professional
}

# macOS/Linux
for f in docs/*.md; do
    node .github/muscles/md-to-word.cjs "$f" --style professional
done

Recursive Directory

# All .md files in docs/ and subdirectories
node .github/muscles/md-to-word.cjs docs --recursive --style professional

Watch Mode

# Auto-rebuild when source changes
node .github/muscles/md-to-word.cjs spec.md --watch

Integration Examples

GitHub Actions CI/CD

# Generate Word docs as build artifacts
- name: Generate Word Documents
  run: |
    npm install -g @mermaid-js/mermaid-cli svgexport
    node .github/muscles/md-to-word.cjs docs/spec.md --toc --cover
    
- name: Upload artifacts
  uses: actions/upload-artifact@v4
  with:
    name: word-documents
    path: docs/*.docx

npm Script

{
  "scripts": {
    "docs:word": "node .github/muscles/md-to-word.cjs docs/README.md --style professional --toc"
  }
}

For Heir Projects

1. Copy .github/muscles/md-to-word.cjs to your project
2. Copy shared modules from .github/muscles/shared/ (markdown-preprocessor, mermaid-pipeline)
3. Install prerequisites: npm install -g @mermaid-js/mermaid-cli svgexport
4. Run: node .github/muscles/md-to-word.cjs your-doc.md

Version History

Conversion Acceptance Decision Table

Related Skills