md2x

Markdown to everything. Convert the Markdown your AI assistant produces into polished documents — starting with .docx. Every dependency is pure JavaScript, so there are no native dependencies — nothing to compile and no system binaries (no pandoc, no LaTeX, no headless browser). It runs anywhere Node does: a laptop, a serverless function, or an AI agent sandbox.

See PROJECT.md for the vision, architecture, and roadmap.

Install

npm install @eswar2000/md2x        # library
npm install -g @eswar2000/md2x     # global CLI

CLI

# Convert a file (writes report.docx next to it)
md2x report.md

# Choose an output name and theme
md2x report.md -o final.docx --theme serif

# Pipe from stdin (great for AI pipelines)
cat notes.md | md2x - -o notes.docx

# List available themes
md2x --list-themes

Options

| Flag | Description | Default | | ------------------- | ---------------------------------------- | -------- | | -o, --output | Output file path | <input>.docx | | -f, --format | Output format (docx) | docx | | -t, --theme | Theme name (clean, compact, serif) | clean | | --list-themes | Print available themes and exit | — |

Library

import { convert } from "@eswar2000/md2x";
import { writeFile } from "node:fs/promises";

const markdown = "# Hello\n\nThis is **md2x**.";
const { buffer, extension } = await convert(markdown, {
  format: "docx",
  theme: "clean",
});

await writeFile(`hello.${extension}`, buffer);

Frontmatter is mapped to document metadata automatically:

---
title: Quarterly Report
author: Ada Lovelace
keywords: finance, q3
---

MCP server

md2x ships an MCP server (md2x-mcp) so any MCP-capable AI client can turn the Markdown it writes into a .docx on demand. It exposes two tools: create_docx (convert Markdown and save a Word file) and list_themes.

Point your client at the md2x-mcp binary over stdio:

{
  "mcpServers": {
    "md2x": {
      "command": "npx",
      "args": ["-y", "--package", "@eswar2000/md2x", "md2x-mcp"]
    }
  }
}

Supported Markdown

md2x maps Markdown — plus a handful of inline HTML tags — onto native Word constructs, not screenshots or approximations. Headings become real heading styles (and appear in the Navigation pane), the table of contents is a live field, lists carry proper numbering, and equations are editable Word math.

Text & inline formatting

| Markdown | Word result | | --- | --- | | **bold** | Bold run | | *italic* / _italic_ | Italic run | | ~~strikethrough~~ | Strikethrough run | | `inline code` | Monospaced run with light shading | | <u>underline</u> | Underlined run | | <sub>x</sub> / <sup>x</sup> | Subscript / superscript (e.g. CO₂, 2³) | | <mark>text</mark> | Yellow highlight | | <kbd>key</kbd> | Monospaced run with light shading | | <abbr title="…">term</abbr> | Dotted-underlined abbreviation | | <small>text</small> | Reduced-size run | | <cite>source</cite> | Italic citation | | <br> | Hard line break within a paragraph | | :emoji: | Unicode emoji (:rocket: → 🚀) | | $inline math$ | Inline, editable Word equation (LaTeX) |

Headings, paragraphs & rules

| Markdown | Word result | | --- | --- | | # … ###### | Built-in Heading 1–6 styles (collapsible, in the Navigation pane) | | Paragraph text | Body paragraph (a single newline is a soft wrap; a blank line starts a new paragraph) | | Two trailing spaces or a trailing \ | Hard line break | | --- | Horizontal rule |

Lists

| Markdown | Word result | | --- | --- | | - item / * item | Bulleted list; nesting uses •, ◦, ▪ | | 1. item | Numbered list with real Word numbering | | Ordered + nested unordered (or vice-versa) | Mixed list — numbers and bullets nest together | | - [x] / - [ ] | Task list with ☑ / ☐ checkboxes | | Multi-paragraph list item | Continuation paragraphs indented under the marker |

Tables

| Markdown | Word result | | --- | --- | | \| a \| b \| with --- / :--: / --: separators | Native Word table with a shaded, bold header row and per-column alignment |

Code blocks

| Markdown | Word result | | --- | --- | | ```lang … ``` fenced block | Shaded, monospaced block with syntax highlighting for 37 languages |

Blocks are highlighted from their language tag using highlight.js's common set (ts, python, go, sql, bash, json, yaml, … 37 languages, with aliases such as js / py / sh / yml). Tabs and indentation are preserved; unknown or unlabeled blocks render as plain monospace.

Blockquotes & callouts

| Markdown | Word result | | --- | --- | | > quote | Boxed quote with a colored left bar; can hold lists, code, and nested quotes | | > [!NOTE\|TIP\|IMPORTANT\|WARNING\|CAUTION] | GitHub-style callout — tinted box, colored bar, icon + label |

Links & table of contents

| Markdown | Word result | | --- | --- | | [text](https://…) | External hyperlink | | [text](#heading-title) | Internal link that jumps to the matching heading | | A ## Table of Contents heading | Native, pre-populated Word TOC field (Heading 1–3, dot leaders, clickable, updatable) |

Images, math & footnotes

| Markdown | Word result | | --- | --- | | ![alt](src) | Embedded image (PNG/JPG/GIF/BMP) from a path, URL, or data: URI; auto-scaled | | $$ block math $$ | Display Word equation, centered (LaTeX) | | text[^id] + [^id]: … | Superscript marker plus a numbered Notes section |

Frontmatter & metadata

| Markdown | Word result | | --- | --- | | YAML frontmatter — standard keys | title, author, subject, keywords, description, revision, lastModifiedBy → Word document properties | | YAML frontmatter — any other keys | Custom Word document properties |

Good to know

• Table of contents — name a heading Table of Contents (or Contents) and md2x drops in a real, pre-filled Word TOC field (the same object as References → Table of Contents). It's populated the moment you open the file, with no "update fields" prompt; press F9 to recompute page numbers. Any link list placed under that heading (handy for GitHub) is replaced by the field.
• Images — src can be a path relative to the Markdown file, an absolute path, an http(s) URL (fetched at convert time), or a data: URI. Oversized images are scaled to fit; unreadable sources fall back to [alt] text.
• Footnotes — gathered into a numbered Notes section where the definitions appear (usually the end), so note text never interrupts the page. Markers are clickable and work in every viewer.
• Math — LaTeX is converted through MathML to OMML, producing real, editable Word equations. Unsupported LaTeX degrades to monospaced text instead of failing.
• Inline HTML — md2x recognizes <u>, <sub>, <sup>, <mark>, <kbd>, <abbr>, <small>, and <cite>; attributes such as <abbr title="…"> are accepted, and the tags nest and combine with **bold** / *italic*.

Examples

Three self-contained documents live under examples/, each focused on a different slice of the feature set. Each folder holds the source .md and a converted .docx.

• example-1 — the main sample: exercises the majority of components (headings, lists, tables, callouts, images, footnotes, the table of contents, and inline formatting).
• example-2 — code-oriented: a code-heavy guide that shows off syntax highlighting across many languages.
• example-3 — math-oriented: a science write-up centered on inline and display equations.

Convert any of them:

md2x examples/example-1/sample.md -o examples/example-1/sample.docx
md2x examples/example-2/rate-limiting.md -o examples/example-2/rate-limiting.docx
md2x examples/example-3/special-relativity.md -o examples/example-3/special-relativity.docx

Development

npm install
npm run build      # bundle with tsup
npm test           # run the vitest suite
npm run typecheck  # type-only check

License

MIT © Eswar V — see LICENSE.