Menú
Convert Word documents (.docx) to clean Markdown with image extraction and pandoc cleanup
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
Create agents that pass agent-review's six gates by construction — role capture, distinct-from-skill check, tool allowlist minimization, draft against gates, dogfood self-review. Use when authoring a new agent, refactoring an existing one, or promoting a Mall agent into the heir's brain.
Audits a candidate agent (.agent.md) against five gates (spec compliance, content quality, scope fit, safety, currency & coherence) plus Gate 6 (tool allowlist minimality). Use when reviewing a new agent draft before commit, evaluating a Mall agent or store agent for adoption, or re-auditing existing agents on a periodic cadence.
Detect, resolve, and manage the Alex_ACT_Memory shared memory bus. Fires on bootstrap, session start (announcements), and feedback writes.
Generate on-brand Alex — ACT Edition SVG banners for documents (READMEs, plans, notes, release artifacts)
Prevent fabricated facts, invented APIs, and citation confabulation at the point of generation. Use when generating factual claims, code examples, API references, library names, configuration values, error messages, or citations — anything where 'sounds plausible' is not the same as 'is real'.
Perform a local brain audit for ACT Edition (and Supervisor) using deterministic QA plus targeted file review, then produce severity-ranked fixes. Pairs with extension-audit on the sibling surface side; the Marketplace surface routes there, not here.
| name | docx-to-md |
| description | Convert Word documents (.docx) to clean Markdown with image extraction and pandoc cleanup |
| lastReviewed | "2026-04-30T00:00:00.000Z" |
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.
| 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 |
# 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
| 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 |
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 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 |
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:
# 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"
# 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
}
| 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 |
winget install pandoc).github/skills/docx-to-md/scripts/docx-to-md.cjs (v1.0.0)
| 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 |
Skill version: 2.0.0 | Last updated: 2026-04-14 | Category: document-conversion