Skip to main content
AI/MLgithub

md-to-docx

Convert Markdown files to professionally formatted Word (.docx) documents with embedded PNG images — pure JavaScript, no external tools required

Stars
34,159
Source
github/awesome-copilot
Updated
2026-05-29
Slug
github--awesome-copilot--md-to-docx
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/github/awesome-copilot/HEAD/plugins/project-documenter/skills/md-to-docx/SKILL.md -o .claude/skills/md-to-docx.md

Drops the SKILL.md into .claude/skills/md-to-docx.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Markdown to Word (.docx) Skill

Convert Markdown (.md) files into professionally formatted Word (.docx) documents with embedded PNG images. Uses pure JavaScript via the docx and marked npm packages — no Pandoc, LibreOffice, or any native binary required.

How to Convert

# Install dependencies (one-time, from the scripts folder)
cd skills/md-to-docx/scripts && npm install

# Convert (run from workspace root)
node skills/md-to-docx/scripts/md-to-docx.mjs <input.md> [output.docx]

If output.docx is omitted, it defaults to <input-basename>.docx in the current directory.

Skill Folder Contents

File Purpose
SKILL.md This instruction file
scripts/md-to-docx.mjs Node.js Markdown-to-Word converter
scripts/package.json Dependencies (docx, marked)

Prerequisites

Requirement Version Notes
Node.js 18+ Required runtime
docx 9+ Pure JS Word document generator
marked 15+ Markdown parser

No native binaries. No system-level installs. Works on Windows, macOS, and Linux.

Features

The converter:

  • Extracts YAML front-matter — uses title, date, version, audience for the title page
  • Generates a title page — with project name, subtitle, date, version, and audience
  • Generates a table of contents — built from H1-H3 headings
  • Embeds PNG images — resolves ![alt](path) references relative to the input .md file, reads the PNG, and embeds it inline in the Word document
  • Styled output — Calibri font, colored headings (#1F3864), styled tables with alternating row colors, code blocks in Consolas
  • Handles all Markdown elements — headings, paragraphs, tables, code blocks, lists, images, links, horizontal rules

Image Embedding

The converter automatically embeds PNG images referenced in the Markdown:

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

The image path is resolved relative to the input Markdown file. The PNG is read, dimensions are extracted from the PNG header, and the image is scaled to fit within 6 inches width while preserving aspect ratio.

If an image file is not found, a placeholder [Image not found: <path>] is inserted.

Front-Matter Format

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

The title is split on — or – into main title and subtitle for the title page.