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

Cleanup and image extraction leave inline, fenced, and indented code unchanged, including examples nested in blockquotes and lists. Heading normalization and comment removal apply outside code. Real media references are copied and verified, including images nested in lists.

Each output owns a separate media directory named after its complete output filename. Converting or reconverting another document in the same folder does not replace the first document's images. Links URL-encode special characters in that directory name. Existing shared images from older conversions are not deleted automatically.

The converter stages Markdown and extracted images together before publishing them. A conversion failure leaves the prior document and media unchanged; handled publication failures roll back files already replaced. If rollback itself fails, the error names retained recovery copies. This is not a power-loss or process-crash transaction guarantee. Windows UNC/network and device image paths are rejected before filesystem access.

Usage

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

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

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

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

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

# Full cleanup pipeline
node 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 below a sibling images/ folder, namespaced by the output filename:

input/
├── document.docx
├── document.md (output)
└── images/
    └── document.md/
        ├── image-001.png
        ├── image-002.png
        └── image-003.jpg

Image references in markdown are updated automatically:

![](images/document.md/image-001.png)

Common Workflows

Stakeholder Document Ingestion

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

# Review the generated markdown and extracted images
git diff -- stakeholder-spec.md images/

Legacy Documentation Migration

# Batch convert all Word docs
Get-ChildItem *.docx | ForEach-Object {
  node 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 — run /alex-act-one setup-dependencies to check and install

Muscle Scripts

skills/docx-to-md/scripts/docx-to-md.cjs

skills/docx-to-md/scripts/validate-md.cjs: post-conversion acceptance checks (heading continuity, footnote sequence, image existence)

Conversion Acceptance Decision Table

Related Skills

• md-to-word - reverse direction (Markdown to Word)
• Markdown linting - validate the output with the project's linter; when Core is installed, its lint-clean-markdown skill provides author-side guidance
• md-to-html - convert result to HTML for web

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