Docx To Md

Ingest Word documents into your Markdown workflow — clean, linted, version-control ready

Convert .docx files into clean, linted Markdown with extracted images, normalized headings, and cleaned table formatting. The reverse converter for ingesting external documents into a Markdown-based workflow.

When to Use

• Importing Word documents from stakeholders into a Markdown-based workflow
• Converting legacy documentation to Markdown for version control
• Extracting content from .docx for further processing (presentations, email, web)
• Onboarding external resources (SOWs, RFPs, specs) into project repositories
• Migrating from Word-based documentation to docs-as-code
• Preparing content for static site generators (VitePress, Docusaurus, etc.)

Supported Content

Key Features

Usage

# Basic conversion
node .github/skills/docx-to-md/scripts/docx-to-md.cjs report.docx

# With frontmatter and heading normalization
node .github/skills/docx-to-md/scripts/docx-to-md.cjs spec.docx --add-frontmatter --fix-headings

# Strip review comments
node .github/skills/docx-to-md/scripts/docx-to-md.cjs reviewed.docx --strip-comments

# Custom output path
node .github/skills/docx-to-md/scripts/docx-to-md.cjs input.docx output/document.md

# Debug mode (keeps raw pandoc output)
node .github/skills/docx-to-md/scripts/docx-to-md.cjs input.docx --debug

# Full cleanup pipeline
node .github/skills/docx-to-md/scripts/docx-to-md.cjs spec.docx --add-frontmatter --fix-headings --strip-comments --clean-tables

Options Reference

Post-Processing Pipeline

The conversion follows a multi-stage cleanup:

.docx → pandoc → raw MD → cleanup → clean MD
                            ↓
                    1. Escaped brackets removed
                    2. Trailing backslashes removed
                    3. Span classes stripped
                    4. Image attributes cleaned
                    5. Comments stripped (optional)
                    6. Headings normalized (optional)
                    7. Tables reformatted
                    8. Images extracted
                    9. Frontmatter added (optional)

Pandoc Cleanup Details

Image Extraction

Embedded images are extracted to a sibling images/ folder:

input/
├── document.docx
└── document.md (output)
    └── images/
        ├── image1.png
        ├── image2.png
        └── image3.jpg

Image references in markdown are updated automatically:

![](images/image1.png)

Common Workflows

Stakeholder Document Ingestion

# Convert with full cleanup
node .github/skills/docx-to-md/scripts/docx-to-md.cjs stakeholder-spec.docx \
  --add-frontmatter --fix-headings --strip-comments

# Validate formatting (exits 1 if file would be reformatted)
node .github/skills/markdown-mermaid/scripts/md-format.cjs stakeholder-spec.md --check

# Review and commit
git add stakeholder-spec.md images/
git commit -m "docs: ingest stakeholder specification"

Legacy Documentation Migration

# Batch convert all Word docs
Get-ChildItem *.docx | ForEach-Object {
  node .github/skills/docx-to-md/scripts/docx-to-md.cjs $_.FullName --add-frontmatter --fix-headings
}

Troubleshooting

Limitations

• Track changes: Accept or reject all changes in Word before converting
• Embedded objects: Charts, SmartArt, etc. must be extracted manually
• Complex tables: Merged cells may not convert cleanly
• Styles: Word styles are lost (only structural elements preserved)
• Headers/footers: Not extracted (document body only)

Requirements

• Node.js 24+
• pandoc (winget install pandoc)

Muscle Script

.github/skills/docx-to-md/scripts/docx-to-md.cjs (v1.0.0)

Conversion Acceptance Decision Table

Related Skills

• md-to-word — Reverse direction (Markdown to Word)
• lint-clean-markdown — Post-validate converted Markdown
• md-to-html — Convert result to HTML for web

Skill version: 2.0.0 | Last updated: 2026-04-14 | Category: document-conversion

Falsifiability

• This skill is wrong if converted documents lose semantic structure (headings, lists, tables) that Pandoc preserves by default without the documented flags
• The flag recommendations are stale if a Pandoc major version changes default behaviors for the documented options
• The workflow is not earning its tokens if the user must manually fix the same structural issues on every conversion