---
title: "Markdown to Word: convert Markdown to docx with pandoc"
slug: markdown-to-word
excerpt: "Read Convert Markdown to Word with one command for the pandoc lines this test ran on notes.md and what they printed."
quickAnswer: "Under Convert Markdown to Word with one command, you'll find the pandoc lines this test ran and the output they printed. The section What to fix after converting covers the image warning and the code block change from this test. Check the numbered reader steps in Checks before you send the file once the docx exists."
keyTakeaways:
  - "The section Convert Markdown to Word with one command shows two pandoc lines and their rc=0 results."
  - "Under Set house styles with a reference doc, the section shows the two commands that name custom-reference.docx."
  - "The section What came back in the round trip quotes the Markdown pandoc gave back from notes.docx."
  - "See Add a contents list to the docx for the T6 run from this test."
  - "Look at Checks before you send the file for the reader steps to run in Word."
publishedDate: 2026-10-21
dateModified: 2026-10-21
author: Bobby Huang
cluster: B
role: post
status: published
faq:
  - q: "Can I convert Markdown to Word without uploading the file?"
    a: "Where pandoc ran in this test is stated under Convert Markdown to Word with one command."
  - q: "What made my image go missing in the docx?"
    a: "Read the diagram.png warning quoted in Convert Markdown to Word with one command."
  - q: "Why did my code block change?"
    a: "Under What came back in the round trip, compare the code line pandoc gave back with the fenced block in notes.md."
  - q: "Can I go back from Word to Markdown?"
    a: "See the pandoc output quoted in What came back in the round trip."
related:
  - markdown-images
  - markdown-tables
  - what-is-a-md-file
---

Need to turn Markdown into an editable Word document? Run one pandoc command on the .md file. Then open the docx in Word and check the headings, tables, images and code yourself.

This guide walks that path with a small test file and quotes what pandoc gave. Every result on this page traces to a single test run. That run used one computer; pandoc there is 3.8.3. If .md files are new to you, read [the primer on .md files and their contents](what-is-a-md-file.md) first.

## Convert Markdown to Word with one command

Our sample file is named notes.md. It has 32 lines: a front matter block, four headings, a bullet list, a numbered list, a table, a Python code block, a quote, a link and an image line. That image line points to diagram.png, and no file by that name was in the test folder. Here is notes.md in full:

````markdown
---
title: Meeting notes
---

# Meeting notes

## Decisions

- Ship the draft on **Friday**.
- Keep the *old* layout for now.

1. Write the summary.
2. Send it to Jane Doe.

## Table

| Item | Owner | Due |
|:-----|:-----:|----:|
| Draft | Jane | Fri |
| Review | John | Mon |

## Code

```python
print("hello")
```

> A quoted line.

See [the guide](https://example.com/guide).

![Diagram](diagram.png)
````

Inside the folder with notes.md, T1 ran this line:

```bash
pandoc notes.md -o notes.docx
```

Pandoc ran on the local machine for this test. It printed one warning line:

```text
[WARNING] Could not fetch resource diagram.png: replacing image with description
```

Even so, T1 finished with rc=0. The file listing after it showed notes.docx at 11554 bytes.

You can also spell out both formats. The test ran this as T2:

```bash
pandoc -f markdown -t docx notes.md -o notes2.docx
```

T2 printed the same warning line as T1 and also ended with rc=0. The two lines differ in what you type. The log doesn't compare the two docx files, so treat them as two routes to try, with T1 as the shorter one to type.

## Set house styles with a reference doc

Say your team wants its own look for headings and body text. The T4 and T5 runs show the two commands for a style file, and the Word steps between them are yours to do.

1. Run the T4 line to write custom-reference.docx:

   ```bash
   pandoc -o custom-reference.docx --print-default-data-file reference.docx
   ```

   In this test, T4 ended with rc=0 and printed no warning.

2. Open custom-reference.docx in Word. Change the styles you care about, such as the heading levels and the body text. Save it under the same name.

3. Convert with the style file named in the command:

   ```bash
   pandoc notes.md --reference-doc=custom-reference.docx -o notes3.docx
   ```

   In this test, T5 printed the diagram.png warning and ended with rc=0.

4. Open notes3.docx in Word. Check that the headings and body text match the styles you set in step 2.

The test left custom-reference.docx as pandoc wrote it, with no style changes. So this run tells you that both lines finished with rc=0. It tells you nothing about how your styles will look, and step 4 is where you find that out.

## What came back in the round trip

For a view of what pandoc kept inside notes.docx, the test turned that file back into Markdown twice. T3 printed its result into the log. T7 wrote it to a file named back.md, and the test then printed back.md. Both gave the same lines:

```text
# Meeting notes

## Decisions

- Ship the draft on **Friday**.
- Keep the *old* layout for now.

1.  Write the summary.
2.  Send it to Jane Doe.

## Table

| Item   | Owner | Due |
|:-------|:-----:|----:|
| Draft  | Jane  | Fri |
| Review | John  | Mon |

## Code

    print("hello")

> A quoted line.

See [the guide](https://example.com/guide).

|         |
|:-------:|
| Diagram |

Diagram
```

Put that next to notes.md and go part by part.

- **Headings.** The four heading lines matched notes.md: `# Meeting notes`, `## Decisions`, `## Table` and `## Code`.
- **Bold and italic.** `**Friday**` and `*old*` came back as written.
- **Bullet list.** Both bullet lines matched.
- **Numbered list.** Both items came back with a double space following the number, as in `1.  Write the summary.`. The source file has one space there.
- **The table.** The header, the two data rows and the cell text matched. The alignment colons in all three columns match notes.md. Pandoc padded the cells with spaces, and the first column's run of dashes grew from five to seven. For the table syntax itself, see [the guide to Markdown tables](markdown-tables.md).
- **Quote and link.** `> A quoted line.` and the link line to example.com matched.
- **Front matter.** The opening three lines of notes.md, `title: Meeting notes` between two `---` lines, are missing from the output.
- **Code block and image.** Both changed shape. The next section covers them.

The file back.md is plain Markdown, so you can read it like any other .md file. If you need a way to view one on your own computer, see [this guide to viewing .md files on a desktop computer](open-and-read-a-markdown-file-on-mac-windows-linux.md).

To go the other way, from a .docx file back to Markdown with its images kept, read [how to convert a Word document to Markdown](word-to-markdown.md).

## What to fix after converting

Pandoc gave back a different shape for two parts of the test file. Below, each part gets what pandoc gave and a fix.

### The missing image

The warning line names diagram.png, the image that notes.md points to. That file did not exist in this test. Pandoc kept going. T1, T2, T5 and T6 each printed the warning, and all four finished with rc=0.

The exit code gave no sign of the missing image in this test. The warning line named it. If you convert from a script, read what pandoc prints as well as the exit code.

In the round trip output, the image line came back as a small table. It has an empty header cell and one cell that reads Diagram, and a plain line reading Diagram follows it. Diagram is the alt text from the image line in notes.md.

To fix it, put the image file where the image line says it is, then run the convert line again. Scan the printed output for a line starting with `[WARNING]`. For how image paths and alt text work in Markdown, see [the guide to Markdown images](markdown-images.md).

### The code block

In notes.md, the code sits in a fenced block with a python label. In the round trip output, that block came back as one line indented by four spaces. It has no fence and no label. The code text itself, `print("hello")`, matched.

The round trip shows what pandoc read back out of the docx. It shows nothing about how the block looks in Word, so check code there with your own eyes. If notes.md stays your master copy, make code fixes in notes.md and run the convert line again. That way the next convert starts from the fixed text.

### Tables with long cells

The test table had short cells with one word each. If your tables hold long text or line breaks inside a cell, read [where Markdown tables break on multiline cells](markdown-table-multiline-cells.md) before you convert. Then give those tables an extra look in the docx.

## Add a contents list to the docx

A longer file can carry a contents list. The test's T6 run took the T1 line, added the `--toc` flag and gave the output a new name:

```bash
pandoc notes.md --toc -o notes4.docx
```

In this test, T6 printed the diagram.png warning and ended with rc=0. The log has no look inside notes4.docx, so it can't tell you what the contents list holds. Open notes4.docx in Word and find the list yourself before you share the file.

## Checks before you send the file

Go over the docx you mean to send with these steps. The log can't do them for you.

1. Read each line pandoc printed. Here, the `[WARNING]` line named the missing diagram.png while the exit code stayed at 0.
2. Open the docx in Word. Scroll the whole file once from top to bottom.
3. Check the headings. Make sure each heading level looks the way you expect next to the body text.
4. Check the tables. Look at the header row, the cell text and the alignment of each column.
5. Check the images. Look for a picture where you expect one, and for alt text standing in where a picture should be.
6. Check the code. Make sure the text and its indentation match your .md file.
7. If you used a reference doc, check that your styles show up on the headings and body text.
8. If you added `--toc`, find the contents list and check that it names your headings.
9. Keep the .md file. If something needs a fix, fix it there and convert again.

## Where Sashmark fits

Nobody has a copy of Sashmark to try; work on the desktop app goes on. Two parts of its plan touch any Markdown file you keep. Round-Trip aims to store a fix you type on the formatted page as that fix alone, leaving each other line as it stood. Changes View aims to flag the parts an agent rewrote while the file sat closed, in a git folder or outside one.

It is in development and has not been released. The app itself has no AI features. See the [planned features](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.

Follow the app's progress at [sashmark.com](https://www.sashmark.com/).