DOCX to Markdown with Images

What It Solves

Converting .docx files to Markdown often loses images, leaves broken absolute paths, and leaves HTML styling behind the text. For engineers who need the output for documentation, search, or further editing, that result is hard to reuse. This skill targets high-fidelity .docx to .md conversion: it preserves headings, tables, lists, bold/italic formatting, and extracts images into usable relative-path assets.

How It Works and Where It Stops

The main workflow prefers pandoc: it checks for pandoc, optionally auto-installs it, runs conversion, then uses fix_images.py to flatten img/media/ into img/, rewrite ![](...) links to relative paths, and remove stray HTML tags or style attributes around images. If pandoc is unavailable, the python-docx fallback can handle headings, inline formatting, nested lists, and tables, but it does not extract images. For non-Word formats such as PDF, PPTX, XLSX, HTML, CSV, JSON, and XML, the skill can try uvx markitdown; on some Windows systems this may fail due to onnxruntime DLL issues, so format-specific tools like python-pptx or openpyxl may be needed. Also, .emf images have poor Markdown viewer compatibility, so converting them to PNG is safer, and GFM output is recommended for broad compatibility.