docx-to-md

Convert Word documents (.docx) to clean Markdown with image extraction and pandoc cleanup

Repository: fabioc-aloha/alex-cognitive-architecture
Last source activity: April 26, 2026 at 18:45
Detected SKILL.md language: English
Stars: 0
Forks: 1

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/fabioc-aloha/alex-cognitive-architecture --skill docx-to-md

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

Word to Markdown Conversion

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

Staleness Watch: See EXTERNAL-API-REGISTRY.md for source URLs and recheck cadence

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

Content Type

Status

Notes

Headings

✅

Hierarchy normalized to start at H1

Bold/Italic

✅

Converted to Markdown syntax

Links

✅

Preserved as Markdown links

Images

✅

Extracted to images/ folder

Tables

✅

Cleaned and aligned

Lists

✅

Ordered, unordered, nested

Code blocks

⚠️

Detected if styled as code

Footnotes

✅

Converted to Markdown footnotes

Comments

⚠️

Stripped with --strip-comments

Track changes

❌

Accept/reject before converting

Embedded objects

❌

Extract manually

type	skill
lifecycle	stable
name	docx-to-md
description	Convert Word documents (.docx) to clean Markdown with image extraction and pandoc cleanup
tier	extended
inheritance	inheritable
applyTo	*/.docx,*/word,/docx*
muscle	.github/muscles/docx-to-md.cjs
currency	2026-04-22T00:00:00.000Z

Word to Markdown Conversion

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

Staleness Watch: See EXTERNAL-API-REGISTRY.md for source URLs and recheck cadence

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

Content Type	Status	Notes
Headings	✅	Hierarchy normalized to start at H1
Bold/Italic	✅	Converted to Markdown syntax
Links	✅	Preserved as Markdown links
Images	✅	Extracted to images/ folder
Tables	✅	Cleaned and aligned
Lists	✅	Ordered, unordered, nested
Code blocks	⚠️	Detected if styled as code
Footnotes	✅	Converted to Markdown footnotes
Comments	⚠️	Stripped with `--strip-comments`
Track changes	❌	Accept/reject before converting
Embedded objects	❌	Extract manually

Feature	Details
Image extraction	Embedded images saved to `images/` folder with sequential naming
Pandoc cleanup	Removes escaped brackets, span classes, trailing backslashes
Table normalization	Aligns columns, adds proper separators
Heading fix	Normalizes hierarchy to start at H1
Frontmatter	Optional YAML frontmatter with title and date
Comment stripping	Removes Word review comments

Option	Default	Description
`--extract-images`	true	Extract images to images/ folder
`--no-extract-images`	-	Keep images as raw base64 in markdown
`--add-frontmatter`	off	Generate YAML frontmatter with title/date
`--clean-tables`	true	Normalize table column widths
`--no-clean-tables`	-	Keep pandoc raw table output
`--fix-headings`	off	Normalize heading hierarchy to start at H1
`--wrap N`	0	Wrap lines at N characters (0 = no wrap)
`--strip-comments`	off	Remove Word comment annotations
`--debug`	off	Keep intermediate pandoc output

Pandoc Quirk	Before	After
Escaped brackets	`\[text\]`	`[text]`
Trailing backslashes	`line\`	`line`
Span classes	`{.underline}`	(removed)
Image attributes	`{width="5in"}`	(removed)
Heading anchors	`{#section-1}`	(removed)
Excessive blank lines	`\n\n\n\n`	`\n\n`

Problem	Cause	Solution
"pandoc not found"	pandoc not installed	`winget install pandoc`
Images missing	Extraction failed	Check images/ folder, re-run
Tables misaligned	Complex table structure	Manual cleanup may be needed
Headings start at H3	Original doc structure	Use `--fix-headings`
Comments in output	Track changes not stripped	Use `--strip-comments`
Encoding issues	Non-UTF8 content	Re-save .docx as UTF-8

Condition	Verdict	Action
All headings mapped to correct `#` levels	Accept	Verify no skipped heading levels
Headings rendered as bold paragraphs instead of `#`	Reject	Check pandoc `--shift-heading-level` and source styles
Tables converted to valid Markdown pipe tables	Accept	Spot-check alignment
Complex tables (merged cells) lose structure	Warning	Manual restructure or use HTML table fallback
Images extracted and linked with relative paths	Accept	Verify image files exist in output dir
Images lost or referenced with absolute Windows paths	Reject	Use `--extract-media` with correct output dir
Footnotes converted to Markdown footnote syntax	Accept	Verify numbering is sequential
Footnotes lost or inlined as parenthetical text	Warning	Check pandoc footnote handling
Code blocks preserve monospace and indentation	Accept	Verify language fence tags present
Track changes / comments stripped from output	Accept	Expected — Markdown has no change tracking
Track changes rendered as visible markup	Reject	Accept or reject all changes before conversion
Bullet and numbered lists preserve nesting	Accept	Verify indent levels match source
Output passes markdownlint with zero errors	Accept	Run `lint-clean-markdown` post-conversion
Round-trip (docx→md→docx) preserves semantic content	Accept	Formatting differences OK; content loss is not

docx-to-md

Install options

Review the source files

Word to Markdown Conversion

When to Use

Supported Content

Word to Markdown Conversion

When to Use

Supported Content

Key Features

Usage

Options Reference

Post-Processing Pipeline

Pandoc Cleanup Details

Image Extraction

Common Workflows

Stakeholder Document Ingestion

Legacy Documentation Migration

Troubleshooting

Limitations

Requirements

Muscle Script

Conversion Acceptance Decision Table

Related Skills

docx-to-md

Source facts

Install options

Review the source files

More from this repository

Word to Markdown Conversion

When to Use

Supported Content

Word to Markdown Conversion

When to Use

Supported Content

More from this repository

Key Features

Usage

Options Reference

Post-Processing Pipeline

Pandoc Cleanup Details

Image Extraction

Common Workflows

Stakeholder Document Ingestion

Legacy Documentation Migration

Troubleshooting

Limitations

Requirements

Muscle Script

Conversion Acceptance Decision Table

Related Skills