Markdown to Word — How to Convert .md to .docx

Why Convert Markdown to Word?

Markdown is a great format for writing: it is fast, plain text, and works with version control. But Word (.docx) is still the standard for distribution. Converting lets you write in Markdown and hand off a document everyone can open.

• Sharing with non-technical colleagues who do not have a Markdown editor and will not open a .md file.
• Submitting reports to a team or manager that expects Word documents with comments and tracked changes.
• Academic papers where journals, universities, or co-authors require .docx submissions.
• Client deliverables such as proposals, specs, and documentation that clients will review and annotate in Word.

Method 1: Pandoc (Best Option)

Pandoc is a free, open-source command-line converter and the gold standard for Markdown to Word. It maps Markdown structure to real Word styles (Heading 1, List Bullet, Table, and so on), so the result is a properly structured document rather than text with manual formatting.

Install it with Homebrew on macOS, then convert:

brew install pandoc

Basic conversion

pandoc input.md -o output.docx

Pandoc infers the output format from the .docx extension. Open output.docx in Word and your headings, lists, links, and tables are all there.

Custom styling with a reference document

To control fonts, colors, and spacing, pass a Word template with --reference-doc:

pandoc input.md -o output.docx --reference-doc=template.docx

See Custom Styling with Reference Docs below for how to create the template.

Useful extras

# Add a table of contents
pandoc input.md -o output.docx --toc

# Convert several files into one document
pandoc intro.md chapter1.md chapter2.md -o book.docx

# Resolve images relative to a folder
pandoc input.md -o output.docx --resource-path=./images

Method 2: VS Code Extensions

If you already write Markdown in Visual Studio Code, extensions can handle the conversion without leaving the editor. Most of them use Pandoc under the hood, so install Pandoc first for the best results.

1. Install Pandoc (see Method 1).
2. Open the Extensions panel (Cmd+Shift+X) and install a Pandoc-based extension such as vscode-pandoc.
3. Open your .md file, run the command palette (Cmd+Shift+P), and choose the Pandoc render command.
4. Pick docx as the output format. The Word file is written next to your Markdown file.

Markdown All in One is the most popular Markdown extension for VS Code. It adds shortcuts, a table of contents, and a Print current document to HTML command. It does not write .docx directly, but you can export HTML and open it in Word (see Method 4). Docs Markdown (from Microsoft) is an authoring toolkit for documentation and also does not export to Word on its own.

Method 3: Online Converters

Web-based tools let you upload or paste Markdown and download a .docx with no installation. Services such as CloudConvert and Convertio accept .md files, and browser editors like Dillinger offer their own export options (often HTML or PDF, which you can then open in Word).

Online converters are fine for one-off conversions of simple files. Keep in mind:

• You are uploading your content to a third-party server, so avoid it for confidential documents.
• Styling options are usually limited, with no custom templates.
• Images referenced by relative path typically will not be found.

Google Docs as a bridge

Google Docs can also act as a converter. Enable Markdown in Tools → Preferences, then paste your Markdown with Edit → Paste from Markdown. Once it is formatted, use File → Download → Microsoft Word (.docx). This works well for short documents with simple formatting.

Method 4: Via HTML

Word can open HTML files and convert them to its own format. This two-step route gives you a chance to adjust the HTML before it reaches Word, which is useful when you need more control over formatting.

Step 1. Convert Markdown to a standalone HTML file:

pandoc input.md -s -o temp.html

Step 2. Open temp.html in Word (File → Open, or right-click and choose Open With → Word).

Step 3. Review the layout, then use File → Save As and choose Word Document (.docx).

Word only honors a subset of CSS, so keep any stylesheet simple. For a deeper look at the first step, see our guide on converting Markdown to HTML.

Method 5: Typora Export

Typora is a WYSIWYG Markdown editor with built-in export. If you already use it, converting to Word is a few clicks:

1. Open your Markdown file in Typora.
2. Choose File → Export → Word (.docx).
3. Choose a location and save.

Typora relies on Pandoc for Word export, so it may prompt you to install it the first time. The result is the same structured document you would get from the command line, without typing any commands.

What Converts Well

Word supports nearly everything standard Markdown can express. The exceptions are things that rely on a browser or a rendering engine.

| Markdown element | Converts? | Notes                                 |
|------------------|-----------|---------------------------------------|
| Headings         | ✅        | Become Word Heading 1-6 styles        |
| Bold / Italic    | ✅        | Preserved exactly                     |
| Links            | ✅        | Clickable hyperlinks                  |
| Lists            | ✅        | Ordered, unordered, and nested        |
| Tables           | ✅        | Basic tables only; limited styling    |
| Code blocks      | ⚠️        | Monospace font; highlighting varies   |
| Images           | ✅        | Embedded if the file path resolves    |
| Footnotes        | ✅        | Become real Word footnotes            |
| Mermaid diagrams | ❌        | Appear as plain code, not as diagrams |

For Mermaid diagrams, render them to PNG or SVG first (for example with the Mermaid CLI) and reference the image in your Markdown.

Custom Styling with Reference Docs

By default, Pandoc output uses its own plain styling. A reference document lets you apply your own look: fonts, heading sizes, colors, spacing, page margins, headers, and footers. Pandoc copies the styles and page setup from the template, then fills in your content.

Step 1. Generate Pandoc's default template so the style names match:

pandoc -o template.docx --print-default-data-file reference.docx

Step 2. Open template.docx in Word and edit the styles (Home → Styles, right-click a style, then Modify). Adjust Heading 1–3, Body Text, Compact (used in lists), Source Code (code blocks), and Table.

Step 3. Add headers, footers, page numbers, and margins through Word's normal page setup, then save the file.

Step 4. Pass the template to Pandoc:

pandoc input.md -o report.docx --reference-doc=template.docx

Only styles and page setup are used from the template. Any body text in it is ignored. Keep one template per document type (report, proposal, paper) and you get consistent, branded output every time.

Common Issues

Images not embedding

Pandoc resolves image paths relative to where you run the command, not where the Markdown file lives. Run the command from the folder containing your Markdown and images, or point to them with --resource-path. Remote images require an internet connection at conversion time.

cd ~/Documents/report
pandoc report.md -o report.docx --resource-path=.:images

Code blocks losing highlighting

Word has no native concept of syntax highlighting. Pandoc applies basic highlighting to fenced code blocks that declare a language (such as ```python), but most other converters output plain monospace text. Adjust the look through the Source Code style in your reference doc, or use --highlight-style to pick a color scheme.

Table formatting is limited

Markdown tables convert to simple Word tables with no merged cells and minimal styling. After conversion, apply a Word table style, or define the Table style in your reference doc so every table looks consistent. Very wide tables may overflow the page.

Custom CSS does not carry over

Word does not render CSS. Any styling from a browser-based Markdown preview, HTML snippets, or inline style attributes is lost. Do the styling in Word (or in a reference doc) instead.

FAQ

How do I convert a Markdown file to Word?

The most reliable way is Pandoc. Install it with brew install pandoc, then run pandoc input.md -o output.docx. If you prefer a graphical tool, Typora exports to Word from File → Export → Word (.docx), and online converters handle simple files.

Can I keep formatting when converting Markdown to Word?

Yes, for everything Markdown can express. Headings, bold, italic, lists, links, tables, images, and footnotes all convert to native Word elements. To control fonts, spacing, and headers or footers, use a styled template with --reference-doc. Custom CSS and Mermaid diagrams do not carry over.

What is the best tool to convert .md to .docx?

Pandoc. It is free, open source, scriptable, and supports custom Word templates. For occasional conversions, Typora's built-in export or an online converter is more convenient.

Preview Your Markdown with MDViewer

Before you convert, check how your document looks. MDViewer is a native macOS app for reading and previewing Markdown files. Double-click any .md file in Finder and see it rendered instantly — headings, tables, code blocks, and images. Not every recipient needs Word, either: PDF export is a quick alternative when you just need a polished, shareable file. Lite is free; Pro adds editing, Git history, and PDF export.

Requires macOS 13.0 or later. Intel and Apple Silicon.