Md To DOCX

Markdown to Word docx

Convert a Markdown .md file into a styled Word .docx document; parse YAML front-matter, headings, tables, lists, code, links, horizontal rules, and PNG image references, then emit a portable document using the bundled Node.js script.

When to invoke

• "Convert this Markdown file to Word."
• "Generate a .docx from this .md report."
• "Embed the PNG diagrams when creating the Word document."
• "Use the pure JavaScript markdown-to-docx converter."
• "Convert without Pandoc, LibreOffice, or native binaries."

Prerequisites and context

• Node.js 18+ must be available.
• Dependencies are declared in scripts/package.json: docx 9+ and marked 15+.
• Run npm install from the skill's scripts folder before the first conversion or after dependency changes.
• The converter supports PNG image embedding; other image types should be converted to PNG first or expected to degrade.

Procedure

1. Install dependencies once from the scripts folder:

cd skills/md-to-docx/scripts && npm install

2. Convert from the workspace root:

node skills/md-to-docx/scripts/md-to-docx.mjs <input.md> [output.docx]

3. If [output.docx] is omitted, expect <input-basename>.docx in the current directory.
4. Open or inspect the generated .docx only if the task requires verification beyond successful script completion.

Conversion behavior

Image embedding

The converter resolves image paths relative to the input Markdown file, reads the PNG header to determine dimensions, and scales each image to fit within 6 inches width while preserving aspect ratio.

![High-Level Architecture](diagrams/high-level-architecture.drawio.png)

Front-matter format

---
title: Project Name — Project Summary
date: 2025-01-15
version: 1.0
audience: Engineering Team, Architects, Stakeholders
---

Styling and package notes

The skill package contains SKILL.md plus converter scripts; the old title used the word SKILL, but the runtime entry point is this Agent Skill. Installation is a one-time dependency step, not a system-level install. Heading color is #1F3864, default output examples may use output.docx, and the document styling uses Calibri headings, alternating table rows, and Consolas code blocks.

Progressive disclosure and bundled resources

Gotchas

• Install from the scripts folder: npm install must run where scripts/package.json lives.
• Run conversion from a predictable workspace root: relative input and output paths are interpreted by the current shell, while images are resolved relative to <input.md>.
• Only PNG images embed: non-PNG Markdown images are not guaranteed to render as embedded Word images.
• Missing images do not stop conversion: the output contains [Image not found: <path>], so inspect the document if image completeness matters.

Output template

## Markdown to docx result

**Status:** converted | blocked
**Input:** `<input.md>`
**Output:** `<output.docx>`
**Command:** `node skills/md-to-docx/scripts/md-to-docx.mjs <input.md> [output.docx]`

### Features used
- Front-matter title page: yes | no
- Table of contents: yes | no
- PNG images embedded: <count or not checked>
- Missing image placeholders: <count or not checked>

### Validation
- Dependencies installed: pass | not needed | fail
- Converter exit status: pass | fail

Quality gate

• Node.js 18+ availability was checked or reasonably established.
• npm install was run in skills/md-to-docx/scripts when dependencies were missing.
• The conversion command used node skills/md-to-docx/scripts/md-to-docx.mjs <input.md> [output.docx].
• The output path behavior was reported, including default <input-basename>.docx when omitted.
• PNG image handling and missing-image placeholders were considered when the Markdown contains images.
• The final .docx path was reported.