How to Convert Markdown to Word (DOCX): Writers' Guide

The Markdown-to-Word Pipeline

Markdown is the preferred writing format for developers, technical writers, and an increasing number of authors and journalists. It is clean, distraction-free, version-control-friendly, and separates content from presentation. But the professional world still runs on Microsoft Word. Editors expect DOCX files. Legal teams redline in Track Changes. Clients want to open attachments in the application they already know.

Converting Markdown to DOCX bridges this gap. You write in Markdown for speed and clarity, then produce a polished Word document for the people who need one. The conversion can preserve your headings, lists, tables, images, footnotes, and even custom styling -- if you set it up correctly.

This guide covers every method for converting Markdown to Word, from quick one-off conversions to automated pipelines with custom templates that produce publication-ready documents.

Method 1: Pandoc (The Gold Standard)

Pandoc is the most powerful and flexible tool for Markdown-to-DOCX conversion. It is a free, open-source universal document converter that handles the conversion with remarkable fidelity.

Installation

# macOS (Homebrew)
brew install pandoc

# Ubuntu/Debian
sudo apt install pandoc

# Windows (Chocolatey)
choco install pandoc

# Or download from pandoc.org

Basic Conversion

# Simple conversion
pandoc input.md -o output.docx

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

# With numbered sections
pandoc input.md -o output.docx -N

That is genuinely all it takes for a basic conversion. Pandoc reads the Markdown, parses headings, paragraphs, lists, code blocks, images, and links, and produces a DOCX file with Word's default styling.

How Markdown Elements Map to Word

Markdown Element	Word Style	Notes
# Heading 1	Heading 1	Creates TOC-compatible heading
## Heading 2	Heading 2	Nests under Heading 1 in navigation
Normal paragraph	Body Text / Normal	Default paragraph style
- Bullet item	List Bullet	Nested bullets supported
1. Numbered item	List Number	Auto-numbered in Word
> Blockquote	Block Text	Indented with left border
inline code	Verbatim Char	Monospaced font
code block	Source Code	Monospaced, may have background
bold	Bold character format	Applied inline
italic	Italic character format	Applied inline
link	Hyperlink	Clickable in Word
	Inline image	Embedded in the DOCX
Footnote[^1]	Word footnote	Proper footnote with superscript

Custom Styling with Reference Documents

The default Pandoc DOCX output uses Word's built-in styles, which are functional but generic. For professional documents, you want custom fonts, colors, spacing, and layout. Pandoc's reference document feature makes this possible.

Creating a Reference Document

1. Generate the default reference:

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

2. Open reference.docx in Microsoft Word
3. Modify the styles (not the content) to match your desired look:
   • Change "Heading 1" style to your preferred font, size, and color
   • Adjust "Body Text" / "Normal" for body paragraphs
   • Customize "Source Code" for code blocks
   • Set page margins, headers, and footers
4. Save the modified reference document

Using the Reference Document

# Apply custom styling
pandoc input.md -o output.docx --reference-doc=reference.docx

# Combine with TOC and numbered sections
pandoc input.md -o output.docx \
  --reference-doc=reference.docx \
  --toc \
  --toc-depth=3 \
  -N

Every DOCX file Pandoc generates will now use your custom styles. The reference document acts as a template -- Pandoc creates new content and applies the styles from the reference.

Style Names That Matter

When customizing the reference document, these are the Word styles Pandoc uses:

Method 2: Online Conversion Tools

For users who prefer not to install software or need a quick conversion:

The document converter on ConvertIntoMP4 handles Markdown-to-DOCX conversion. Upload your .md file, select DOCX as the output, and download the result. This is ideal for one-off conversions or when you do not have Pandoc installed.

For Markdown files that you want in PDF instead, the process is similar. See our Markdown to PDF guide for that specific workflow, or upload directly to the document converter and select PDF as the output format.

Method 3: VS Code Extensions

If you write Markdown in Visual Studio Code, several extensions add DOCX export:

Markdown All in One -- provides export to various formats via Pandoc integration.

Docs-to-Markdown -- bidirectional conversion between Google Docs and Markdown.

The typical VS Code workflow:

1. Write in Markdown with live preview
2. Install the Pandoc extension or use a task runner
3. Configure a build task that runs Pandoc with your reference document
4. Export via the command palette or keyboard shortcut

Handling Images

Images require attention during conversion because Markdown references them by path, but DOCX embeds them directly.

Local Images

![Architecture diagram](./images/architecture.png)

Pandoc resolves the path relative to the input file's directory and embeds the image in the DOCX. Supported formats: PNG, JPG, GIF, SVG (converted to EMF), and BMP.

Remote Images

![Logo](https://example.com/logo.png)

Pandoc downloads remote images during conversion and embeds them. This requires an internet connection during the conversion. If you plan to convert offline, download images locally first.

Image Sizing

Pandoc supports image attributes for sizing:

![Diagram](./diagram.png){width=50%}
![Photo](./photo.jpg){width=3in height=2in}

Without explicit sizing, images appear at their native resolution, which may be too large for the page. Always specify width for images wider than the text area.

If you need to resize images before conversion, our resize image tool handles batch resizing, and the image converter can change formats if needed (e.g., converting WebP images to PNG for better Word compatibility).

Handling Tables

Markdown tables convert well to Word tables, but there are nuances:

Pipe Tables (Standard)

| Feature | Status      | Priority |
| ------- | ----------- | -------- |
| Auth    | Complete    | High     |
| Search  | In Progress | Medium   |
| Export  | Planned     | Low      |

This produces a basic Word table with borders. The styling comes from the reference document's table style.

Grid Tables (More Features)

For more complex tables with multi-line cells, use Pandoc's grid table syntax:

+----------+-----------+----------+
| Feature | Status | Priority |
+==========+===========+==========+
| Auth | Complete | High |
| | | |
| | Includes | |
| | 2FA | |
+----------+-----------+----------+
| Search | In | Medium |
| | Progress | |
+----------+-----------+----------+

Grid tables support multi-line cell content, column spanning, and more precise alignment.

YAML Metadata for Document Properties

Pandoc's YAML front matter maps to Word document properties:

---
title: "Project Status Report"
author: "Engineering Team"
date: "February 2026"
abstract: |
  This report covers Q1 progress on the platform
  migration project, including milestones completed,
  risks identified, and next steps.
subtitle: "Q1 2026"
keywords: ["engineering", "migration", "quarterly"]
lang: en-US
---

The title, author, date, and abstract appear in the document body. The keywords and lang become Word document metadata visible in File > Properties.

Automating the Conversion

Makefile Approach

PANDOC = pandoc
REF_DOC = templates/reference.docx
MD_FILES = $(wildcard docs/*.md)
DOCX_FILES = $(MD_FILES:.md=.docx)

all: $(DOCX_FILES)

%.docx: %.md $(REF_DOC)
	$(PANDOC) $< -o $@ --reference-doc=$(REF_DOC) --toc -N

clean:
	rm -f docs/*.docx

Shell Script

#!/bin/bash
# Convert all Markdown files in a directory to DOCX

INPUT_DIR="./docs"
OUTPUT_DIR="./output"
REF_DOC="./templates/reference.docx"

mkdir -p "$OUTPUT_DIR"

for md in "$INPUT_DIR"/*.md; do
  filename=$(basename "$md" .md)
  echo "Converting: $filename"
  pandoc "$md" -o "$OUTPUT_DIR/${filename}.docx" \
    --reference-doc="$REF_DOC" \
    --toc \
    --toc-depth=3 \
    -N \
    --wrap=none
done

echo "Conversion complete."

For more on building automated conversion pipelines, see our guide on how to automate file conversions. If you are working with batch processing across multiple formats, our batch processing guide covers the broader workflow.

Collaborative Workflows: Markdown + Word

The most practical workflow for teams with mixed preferences:

1. Authors write in Markdown using their preferred editor (VS Code, Obsidian, Emacs, Vim, etc.)
2. Convert to DOCX using Pandoc with a shared reference document
3. Editors review in Word using Track Changes and comments
4. Authors incorporate feedback by reading the DOCX comments and updating the Markdown source
5. Reconvert for the next review cycle

This is a one-directional workflow: Markdown is the source of truth, and DOCX is the output format. Do not try to convert the edited DOCX back to Markdown -- the round-trip introduces formatting artifacts. Instead, read the Word feedback and apply it to your Markdown source manually.

For Bidirectional Workflows

If you genuinely need to convert Word documents back to Markdown (e.g., when receiving a DOCX from a co-author who writes in Word):

pandoc input.docx -o output.md --wrap=none

The output Markdown will be clean but may need manual adjustment for complex formatting. Track Changes and comments are not preserved. For converting existing Word documents to other formats, see our guide on how to convert DOC to DOCX for handling legacy Word formats.

Troubleshooting

Images Not Appearing

• Verify the image paths are correct relative to the Markdown file
• Check that the image files exist at the specified paths
• For remote images, ensure internet connectivity during conversion
• Try using absolute paths if relative paths fail

Tables Look Different Than Expected

• Ensure your Markdown table syntax is valid (consistent pipe characters, separator row)
• Check the table style in your reference document
• For very wide tables, consider landscape page orientation or reducing column count

Fonts Not Matching the Reference Document

• Verify the fonts are installed on the system running Pandoc
• Use standard fonts (Times New Roman, Arial, Calibri) for maximum compatibility
• For custom fonts, embed them in the DOCX using Word's font embedding option

Code Blocks Not Formatted Correctly

• Ensure fenced code blocks use triple backticks with a language identifier
• Customize the "Source Code" style in your reference document
• For syntax highlighting in DOCX, use the --highlight-style flag

Beyond DOCX: Other Output Formats

Pandoc's strength is its universality. The same Markdown source can produce:

• PDF via LaTeX -- see our Markdown to PDF guide
• HTML for web publishing
• EPUB for ebook readers -- see our best ebook format guide
• PPTX for presentations
• LaTeX for academic submissions

The document converter supports many of these conversions online, and the pdf-to-epub tool handles specific format pairs when you need to go from PDF output to ebook format.

Wrapping Up

Markdown-to-DOCX conversion with Pandoc is mature, reliable, and highly customizable. The basic command (pandoc input.md -o output.docx) handles 80% of use cases. A custom reference document handles the next 15%. The remaining 5% involves edge cases with complex layouts that are better handled natively in Word after conversion.

The key insight is that Markdown should be your source format and DOCX your output format. Write in Markdown for its clarity and version control benefits, convert to Word for the people who need it, and keep the Markdown as your canonical document. This workflow gives you the best of both worlds: a clean authoring experience and professional-looking output.