md-to-docx

English | 中文

md-to-docx

The open-source document compiler for the AI era.

    AI / Markdown
          ↓
    Professional DOCX

Install · GitHub

Why md-to-docx?

✓ AI → Word — compile AI drafts into deliverable DOCX (agents)
✓ Markdown → DOCX — md-to-docx report.md --preset technical
✓ DOCX → Markdown — md-to-docx reverse report.docx
✓ Document Diff — structural compare for .md and .docx (roundtrip)
✓ Templates — presets + community Word templates (presets · templates)
✓ MCP — convert, validate, apply_template, list_presets, reverse, diff (mcp)
✓ Cursor / Claude / Codex / Gemini — SKILL.md · skills/
○ Browser Extension (experimental) — export ChatGPT / Claude / Gemini chats (extension)
○ Desktop context menu (experimental) — Finder / Explorer right-click .md ↔ .docx (desktop)
✓ GitHub Action — CI builds DOCX from Markdown (action)
✓ Local & Private — no API keys, self-host with Docker

30 seconds demo

input.md  →  md-to-docx  →  report.docx

./bin/convert examples/technical-report/example.md --preset technical

Before (Markdown) → After (Word)

AI Workflow

ChatGPT · Claude · Cursor · Codex · Gemini
                  ↓
              md-to-docx
                  ↓
         Professional Word

SKILL.md · Use with AI agents · MCP server

Templates

Technical · Business · Academic · Chinese · API · Meeting

See the full examples gallery.

Ecosystem

Core: CLI · MCP · GitHub Action · Docker Playground

Experimental (need local CLI or Playground): VS Code · Obsidian · Browser · Desktop

Quick Start

Option A — Git clone (recommended, no pip)

git clone https://github.com/sunliang11/md-to-docx.git
cd md-to-docx
./bin/convert path/to/report.md --preset technical

Option B — Docker Playground (no local Python)

docker compose -f web/docker-compose.yml up --build
# open http://localhost:8080

Option C — Local Web Playground (pip + uvicorn)

pip install -e ".[web]"
PYTHONPATH=scripts python -m md_to_docx.presets_build
uvicorn web.app:app --reload --port 8080
# open http://localhost:8080

Modes: Convert (presets, TOC, numbering, community templates, ODM syntax inserts, validate, engine preview, export DOCX), Reverse (DOCX → Markdown), Diff (structural compare). MCP / editors / GitHub Action stay in their own docs.

Option D — Desktop context menu (Finder / Explorer)

Requires md-to-docx on your PATH (see Install). Then:

# macOS
bash desktop/macos/install.sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File desktop/windows/install.ps1

Right-click .md → Word; right-click .docx → Markdown. Details and uninstall: desktop/README.md.

Commands

md-to-docx report.md --preset technical                              # convert (default)
md-to-docx reverse report.docx                                        # DOCX → Markdown (same dir, report.md)
md-to-docx diff draft-v1.md draft-v2.md --format md                  # structural diff
md-to-docx report.md --plugin examples/plugins/uppercase_headings.py   # custom plugin
md-to-docx report.md --check                                         # validate only

Full option reference → references/cli.md (all subcommands, flags, install methods, and troubleshooting).

Subcommands: convert (default), reverse, diff, build, mcp. Legacy md-to-docx file.md still works.

Batch & directories

md-to-docx ./docs --output-dir ./output --exclude "README.md"
md-to-docx ./docs --dry-run

What you can do

What	One-liner	Try
Convert	Compile Markdown or AI drafts into professional DOCX	`md-to-docx report.md --preset technical`
Reverse	Turn DOCX back into editable Markdown (native AST)	`md-to-docx reverse report.docx`
Diff	Compare two versions by document structure (.md or .docx)	`md-to-docx diff v1.md v2.md --format md`
Validate	Lint Markdown before shipping — no DOCX output	`md-to-docx report.md --check`
Extend	Hook custom transforms with a small Python plugin	`md-to-docx report.md --plugin my_plugin.py`
Automate (CI)	Build DOCX in GitHub Actions; keep `.md` in Git	`uses: sunliang11/md-to-docx/action@v1.1.0`
Editor export	Right-click in VS Code or Obsidian → export Word	VS Code · Obsidian
Desktop context menu	Finder / Explorer right-click `.md` ↔ `.docx`	desktop/README.md
AI agents	Cursor / MCP / browser — local, no API keys	SKILL.md · MCP

Pipeline: Markdown / AI output → Document AST → Professional DOCX (and back).

Choose how to run it

Entry	Status	One-liner	Doc
CLI	Core	Full command-line tool (`md-to-docx`)	CLI Reference
`bin/convert`	Core	Run from a git clone without `pip install`	—
Python API	Core	`from md_to_docx.api import convert` for scripts	development.md
Cursor Skill	Core	Agent picks a preset and converts for you	SKILL.md
Claude / Codex / Gemini	Core	Platform-specific skill copies	skills/
MCP	Core	Four tools: convert, validate, apply_template, list_presets	mcp.md
Web Playground	Core	Edit in browser, download DOCX (Docker)	web/README.md
GitHub Action	Core	CI builds DOCX from Markdown	action/README.md
Browser extension	Experimental	Export ChatGPT / Claude / Gemini chats (needs local Playground)	browser-extension/README.md
VS Code	Experimental	Local VSIX / Extension Development Host — not on Marketplace	editors/vscode/README.md
Obsidian	Experimental	Manual install — no settings UI yet	editors/obsidian/README.md
Finder / Explorer	Experimental	One-click system context menu for `.md` / `.docx`	desktop/README.md

Document support

Native AST engine — Document AST → professional DOCX
Structure — headings, lists, tables, code, blockquotes, images, task lists
Footnotes — Markdown [^id] refs render as superscript numbers plus a trailing Notes section (not Word footnotes.xml yet)
CJK — Microsoft YaHei / SimSun templates
Mermaid — PNG when mmdc is installed; degrades to code block otherwise
Math — basic LaTeX → OMML (subset; complex MathML falls back to plain text)
Captions & cross-refs — {#fig:id}, [@fig:id], Table: … {#tbl:id}
TOC & page numbers — Word-native fields, header/footer
Page breaks —  in Markdown
Frontmatter — YAML metadata (title, author, date, toc, …); CLI flags still required for preset/template

See presets, roundtrip, plugins.

Examples

Seven ready-made reports in examples/: technical, business, academic, API, meeting notes, AI report, Chinese report — each with example.md and compiled example.docx. Plugin sample: examples/plugins/.

Git workflow

Keep Markdown in Git; treat DOCX as a build artifact:

dist/docx/
*.docx

- uses: sunliang11/md-to-docx/action@v1.1.0
  with:
    input: docs/report.md
    preset: technical
- uses: actions/upload-artifact@v4
  with:
    name: docx
    path: dist/docx

See action/README.md. Roadmap: references/roadmap.md.

Community templates

Browse contributed Word templates in templates/. Use any template with --template:

md-to-docx report.md --template templates/technical-design/template.docx

To contribute a template, see the PR checklist in templates/README.md. Document syntax: spec/document-markdown.md (ODM odm-0.1).

Install

Requirements

Python 3.10+
mmdc — only if you need Mermaid rendered as images (installation.md)

From source (development)

git clone https://github.com/sunliang11/md-to-docx.git
cd md-to-docx
pip install -e ".[dev]"      # or -e ".[mcp]" / -e ".[web]"
which md-to-docx             # verify CLI is on PATH
md-to-docx report.md         # or ./bin/convert report.md (no pip)

Install options and entry points: CLI Reference — How to run commands.

Not on PyPI yet. Planned package name: md2docx-compiler · CLI command: md-to-docx. Install from source or pip install "git+https://github.com/sunliang11/md-to-docx.git". After the first publish (see release.md), pip install md2docx-compiler will work.

Mermaid note: Without mmdc, diagrams appear as source code blocks. Use --strict-mermaid to fail instead. Full matrix: installation.md.

Documentation

CLI Reference — all commands, flags, install methods
Installation & troubleshooting
Presets
Validation
Roundtrip / reverse / diff
Plugin API
MCP server
Use with AI agents
GitHub Action
Web Playground
Browser extension
Desktop context menu
VS Code extension
Obsidian plugin
Examples gallery
Example plugins
Environment variables
Contributing
Development & tests
Release process
Roadmap

Cursor Skill

ln -sfn /path/to/md-to-docx ~/.cursor/skills/md-to-docx

See SKILL.md for agent instructions.

License

MIT — see LICENSE.

Star History

GitHub restricted public stargazer API access in 2026, so hosted api.star-history.com badges no longer work for most repos. This chart is generated by .github/workflows/star-history.yml and committed into the repo.

Navigation Menu

Repository files navigation

md-to-docx

The open-source document compiler for the AI era.

Why md-to-docx?

30 seconds demo

AI Workflow

Templates

Ecosystem

Quick Start

Commands

What you can do

Choose how to run it

Document support

Examples

Git workflow

Community templates

Install

Requirements

From source (development)

Documentation

Cursor Skill

License

Star History

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.devcontainer		.devcontainer
.github		.github
action		action
aim		aim
assets		assets
bin		bin
browser-extension		browser-extension
desktop		desktop
editors		editors
examples		examples
references		references
scripts		scripts
skills		skills
spec		spec
templates		templates
tests		tests
web		web
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README.zh.md		README.zh.md
SECURITY.md		SECURITY.md
SKILL.md		SKILL.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

md-to-docx

The open-source document compiler for the AI era.

Why md-to-docx?

30 seconds demo

AI Workflow

Templates

Ecosystem

Quick Start

Commands

What you can do

Choose how to run it

Document support

Examples

Git workflow

Community templates

Install

Requirements

From source (development)

Documentation

Cursor Skill

License

Star History

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages