Markdown to Word: How to Convert .md to .docx (2026)

TL;DR: The fastest way to convert Markdown to Word on macOS is Pandoc: brew install pandoc, then pandoc input.md -o output.docx. For corporate documents with custom styles, add --reference-doc=template.docx. Online converters (CloudConvert) work for one-off files but upload your content to a third-party server. Preview your Markdown first in MacMD Viewer to catch formatting issues before converting.

Markdown is the preferred format for writing documentation, README files, and technical notes — but at some point, someone on your team will ask for a Word document. Whether it is a client deliverable, a legal review, or a corporate template requirement, .docx is still the lingua franca of office collaboration.

Converting Markdown to Word is not as simple as copy-pasting the rendered output. A proper conversion needs to map Markdown headings to Word heading styles, preserve tables, handle code blocks with monospace formatting, and carry over images and footnotes. Doing this correctly requires the right tool and the right workflow.

This guide covers every practical method — from Pandoc on the command line to online converters and Python scripting — with the exact commands for macOS. For converting Markdown to PDF instead, see the Markdown to PDF on Mac guide or the general Markdown to PDF guide.

What Is the Best Way to Convert Markdown to Word?

Pandoc is the gold standard for Markdown to Word conversion. It handles the full CommonMark specification — tables, fenced code blocks, footnotes, blockquotes, images, and nested lists — and maps each element to the appropriate Word paragraph style. Every other method is either a wrapper around Pandoc or a less capable alternative.

The choice of method depends on your workflow:

For most users, Pandoc is the answer. The others are situational.

How Do You Install Pandoc on macOS?

Pandoc installs in one command via Homebrew. Open Terminal and run:

brew install pandoc

Homebrew downloads and installs the Pandoc binary globally. Verify the installation:

pandoc --version

You should see output like pandoc 3.x.x. No additional dependencies are needed for .md to .docx conversion — Pandoc handles everything natively.

If you do not have Homebrew, install it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Alternatively, download the macOS .pkg installer from pandoc.org/installing if you prefer not to use Homebrew.

How Do You Convert Markdown to Word with Pandoc?

The basic conversion is a single command. Navigate to the folder containing your Markdown file and run:

pandoc input.md -o output.docx

Pandoc infers the output format from the file extension. The result is a .docx file in the same directory, with Word paragraph styles applied automatically:

• # Heading 1 → Word Heading 1 style
• ## Heading 2 → Word Heading 2 style
• Paragraphs → Word Normal style
• ```code``` blocks → Word Verbatim style (monospace)
• | table | → Word table with borders
• > blockquote → Word Block Text style

Converting multiple files at once

Pandoc accepts multiple input files and concatenates them:

pandoc chapter1.md chapter2.md chapter3.md -o book.docx

Specifying the input format explicitly

If your file uses a non-standard extension, specify the format:

pandoc input.txt -f markdown -o output.docx

The -f markdown flag tells Pandoc to parse the input as CommonMark Markdown regardless of the file extension.

How Do You Apply a Custom Word Template with Pandoc?

For corporate documents, you need the output to match your organisation's heading styles, fonts, and paragraph formatting. Pandoc supports this via a reference .docx file:

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

Pandoc reads the styles from template.docx and applies them to the converted content. It copies the style definitions (fonts, colours, spacing) not the content — your Markdown text fills the document, styled according to your template.

How to create the reference template

1. Open a blank .docx in Microsoft Word
2. Define the styles you need: Heading 1, Heading 2, Normal, Verbatim (for code), Block Text (for blockquotes)
3. Set your organisation's fonts, colours, and paragraph spacing for each style
4. Save the file as template.docx
5. Pass it to Pandoc with --reference-doc=template.docx

The reference doc approach is the standard workflow for organisations that publish Markdown internally but deliver Word documents to clients or regulators. It eliminates manual reformatting after conversion.

Useful Pandoc flags for Word output

# Table of contents
pandoc input.md --toc -o output.docx
 
# Number headings (1.1, 1.2, etc.)
pandoc input.md --number-sections -o output.docx
 
# Combine template + TOC + numbered headings
pandoc input.md --reference-doc=template.docx --toc --number-sections -o output.docx

Can You Convert Markdown to Word in VS Code?

VS Code does not export to .docx natively. However, the vscode-pandoc extension adds Pandoc integration directly to the editor. With it installed, you can open the command palette (Cmd+Shift+P) and run "Pandoc Document Exporter: Export as Word Document" without leaving VS Code.

Requirements: Pandoc must be installed on your system (see the Homebrew step above). The extension is a UI wrapper — it calls the same pandoc binary under the hood.

To install:

1. Open VS Code Extensions (Cmd+Shift+X)
2. Search for "vscode-pandoc" (by DougFinke)
3. Install and reload
4. Open your .md file, open the command palette, and run the export command

The extension also supports PDF and HTML export via the same command palette. If Pandoc is not found, the extension will prompt you to configure the binary path in VS Code settings.

Note: The popular Markdown All in One extension (yzhang.markdown-all-in-one) does not export to .docx. It focuses on editing experience — shortcuts, table of contents, list formatting. Do not confuse the two.

What Online Tools Convert Markdown to Word?

Online converters are suitable for one-off conversions when you do not want to install anything. The main options are:

CloudConvert (cloudconvert.com) — Supports Markdown to DOCX directly. Upload your .md file, select DOCX as output, and download the result. CloudConvert uses Pandoc under the hood. Free tier has conversion limits; paid plans available.

Pandoc Online (pandoc.org/try) — The official Pandoc demo converts between formats. Limited to smaller documents; not designed for production use.

Word2MD / Markdown converters — Several other tools exist, but most are Pandoc wrappers with varying rate limits and quality.

Privacy tradeoff: Every online converter uploads your file content to a third-party server. For confidential documents — internal proposals, legal documents, client work — use Pandoc locally instead. Local conversion keeps your content on your machine.

How Do You Convert Markdown to Word with Python?

For programmatic conversion inside a pipeline or application, Python offers two approaches.

Option 1: Call Pandoc as a subprocess (recommended)

import subprocess
 
def markdown_to_docx(input_path: str, output_path: str, template_path: str | None = None) -> None:
    cmd = ["pandoc", input_path, "-o", output_path]
    if template_path:
        cmd += ["--reference-doc", template_path]
    result = subprocess.run(cmd, capture_output=True, text=True)
    if result.returncode != 0:
        raise RuntimeError(f"Pandoc conversion failed: {result.stderr}")
 
markdown_to_docx("input.md", "output.docx", template_path="template.docx")

This approach has the same output quality as running Pandoc directly and avoids reimplementing conversion logic.

Option 2: python-docx + markdown library

For cases where you cannot depend on a system Pandoc binary:

pip install python-docx markdown beautifulsoup4

import markdown
from bs4 import BeautifulSoup
from docx import Document
 
def md_to_docx(md_text: str, output_path: str) -> None:
    html = markdown.markdown(md_text, extensions=["tables", "fenced_code"])
    soup = BeautifulSoup(html, "html.parser")
    doc = Document()
 
    for element in soup.children:
        tag = getattr(element, "name", None)
        if tag in ("h1", "h2", "h3"):
            level = int(tag[1])
            doc.add_heading(element.get_text(), level=level)
        elif tag == "p":
            doc.add_paragraph(element.get_text())
        elif tag == "pre":
            doc.add_paragraph(element.get_text(), style="No Spacing")
 
    doc.save(output_path)

This approach gives you fine-grained control over the Word document structure but requires more code to handle every Markdown element correctly — tables, nested lists, inline formatting, images. For production use, the Pandoc subprocess approach is more reliable.

What Markdown Features Do Not Convert to Word?

Most Markdown converts cleanly to Word via Pandoc. A few features have limitations worth knowing before you finalize your source document.

Mermaid diagrams — Pandoc does not render Mermaid. If your Markdown contains Mermaid fenced code blocks (```mermaid), they appear as plain code blocks in the Word output. Workaround: export the diagram as a PNG from the Mermaid live editor or from MacMD Viewer, then embed the image in your Markdown before converting. See the Mermaid diagram guide for the full diagram syntax.

Custom HTML — Pandoc passes through raw HTML as plain text in .docx output. Any <div>, <span>, or custom styled elements are stripped or rendered as literal text. Rewrite HTML blocks as native Markdown before converting.

Tables with complex alignment — Basic Markdown tables (| col | col |) convert correctly. Tables with merged cells or complex column spans require post-conversion editing in Word.

Inline math (LaTeX) — Pandoc can handle $equation$ syntax if you pass --mathjax or use the --mathml flag, but Word rendering of math varies. For documents with heavy math, consider converting to PDF instead, where LaTeX renders reliably.

YAML frontmatter — By default, Pandoc strips YAML frontmatter from the output body and uses it for document metadata. Fields like title and author can appear in the Word document header via a metadata block or a custom reference template.

How Should You Preview Markdown Before Converting?

Converting to Word first and then catching formatting problems is expensive — fixing a broken table or missing heading in a .docx requires editing the Word file directly rather than the source Markdown.

A better workflow: preview the Markdown, catch and fix issues in the source, then convert once.

MacMD Viewer renders your Markdown exactly as Pandoc will interpret it — GFM-compatible, with tables, code blocks, and nested lists all visible. Open the .md file in MacMD Viewer while editing in your text editor. The preview updates live, so you see broken syntax the moment you introduce it.

MacMD Viewer is not a converter — it does not produce Word or PDF output. Its role in the workflow is pre-conversion validation:

1. Write and edit your Markdown
2. Preview in MacMD Viewer — fix any table misalignment, heading hierarchy issues, or unrendered code blocks
3. Run pandoc input.md -o output.docx on the validated source
4. Open the .docx and verify styles

This approach produces a cleaner Word document and avoids the back-and-forth of editing Word files to fix source-level Markdown mistakes. ($19.99, one-time purchase, download here.)

What Are the Limitations of Copy-Pasting from a Preview?

Copy-pasting rendered Markdown from a browser or preview pane into Word is the lowest-friction approach for short, simple documents. For anything with real structure, it breaks down quickly.

What copy-paste preserves: Basic bold and italic, paragraph breaks, plain bullet points.

What copy-paste loses: Heading styles (becomes bold Normal text instead of Word Heading styles), code block monospace formatting, table cell borders, blockquote indentation, and link URLs (the link text copies but not the href).

The result requires manual reformatting in Word to restore structure — which takes longer than just running Pandoc once. Use copy-paste only for documents under a page with minimal formatting.

Markdown to Word: Method Comparison

Pandoc CLI is the winner for almost every use case. The reference template flag is the differentiator for professional document workflows.

Frequently Asked Questions

How do I convert Markdown to Word on macOS?

Install Pandoc with brew install pandoc, then run pandoc input.md -o output.docx in Terminal. This produces a Word document with correct heading styles, tables, and code blocks. For documents that need to match a corporate template, pass --reference-doc=template.docx to apply your organisation's styles.

Does Pandoc preserve Markdown headings as Word heading styles?

Yes. Pandoc maps # Heading 1 to the Word Heading 1 paragraph style, ## Heading 2 to Heading 2, and so on through ###### Heading 6. If you use a reference .docx template, Pandoc applies the font, colour, and spacing from your template's heading styles to the converted headings.

Can I convert a Markdown file with images to Word?

Yes. Pandoc embeds images referenced in your Markdown (![alt text](path/to/image.png)) into the .docx file. Use relative paths from the Markdown file's directory. Remote image URLs also work, but Pandoc must be able to fetch them during conversion.

What is the difference between Markdown to Word and Markdown to PDF?

Word (.docx) output is editable — recipients can modify the document, track changes, and comment. PDF output is a fixed layout, suitable for final deliverables that should not be edited. For Pandoc, the only difference is the output extension: -o output.docx versus -o output.pdf (PDF also requires a LaTeX distribution or --pdf-engine=weasyprint). See the Markdown to PDF guide for the full PDF workflow.

Why does my converted Word document look unstyled?

Without a reference template, Pandoc applies its default Word styles, which use generic fonts and basic formatting. To get professionally styled output, create a reference .docx with your desired heading and paragraph styles, then pass it with --reference-doc=your-template.docx. The Pandoc documentation explains how to configure each style in the template.