Writing in Markdown is a pleasure. The trouble starts when the person you’re sending it to wants a Word file.
An internal request form, a conference abstract, a deliverable for a client. The people receiving them don’t know Markdown, and they shouldn’t have to. Here are three ways to convert Markdown to Word (.docx) on a Mac, along with who each one suits and who it doesn’t.
Method 1: Pandoc (free, command line)
Pandoc is an open-source tool for converting between document formats. If you have Homebrew, installing it takes one line.
brew install pandocConverting takes one line, too.
pandoc draft.md -o draft.docxHeadings, tables, lists and code blocks are converted straight into Word styles. To match your company’s formatting, prepare a template .docx and have Pandoc use it as a reference.
pandoc draft.md --reference-doc=template.docx -o draft.docx- Best for: people who are comfortable with Terminal and run the same conversion over and over, or who want to build it into a script
- Watch out for: diagrams such as Mermaid don’t become images on their own (you need to pair Pandoc with another tool). Getting the fonts and the table of contents right can also mean spending a lot of time on a template anyway
Method 2: Online converters
Plenty of services will convert a file as soon as you drop it into your browser. Nothing beats them for convenience.
Keep in mind, though, that your document gets uploaded to someone else’s server. Unpublished papers, meeting minutes with customer information and confidential specifications should not go through these services. Some companies explicitly prohibit it.
- Best for: people who only occasionally convert text that’s going to be public anyway
- Not for: anyone who handles confidential documents
Method 3: Use an editor with built-in export
If the app you write in can export .docx itself, that’s the fewest steps of all. There’s no converter to install and nothing to upload.
Our own Markdocx is a Markdown editor for Mac built around this idea.
- Exports Word (.docx) and EPUB by itself. No Pandoc to install or configure, and no command line. It also exports to PDF, HTML and Markdown
- Built-in Mermaid diagrams. Insert any of 10 types, including flowcharts, sequence diagrams and Gantt charts, from the toolbar, and rendering happens entirely on your Mac. No internet connection or outside service is involved
- Live preview. Place it side by side or one above the other, and two-way scroll sync keeps both on the same paragraph
- GitHub Flavored Markdown. Supports tables, task lists, strikethrough and code blocks with syntax highlighting
- Files stay plain .md. You can keep using other editors alongside it
Writing, live preview, Mermaid diagrams and the outline are free with no time limit. You can try every feature for the first 14 days; after that, Markdocx Premium, a one-time purchase, unlocks Word import and export to every format. It’s not a subscription, and it works on every Mac that uses the same Apple Account. Requires macOS 26 or later.
Which one to choose
| Ease of use | Confidentiality | Diagrams (Mermaid) | Cost | |
|---|---|---|---|---|
| Pandoc | △ (CLI) | ◎ (local) | △ (needs another tool) | Free |
| Online converters | ◎ | ✕ (sent to an outside server) | △ | Mostly free |
| Editor with built-in export | ◎ | ◎ (local) | ◎ | One-time purchase |
In short, choose Pandoc to automate repetitive conversions, and an editor with built-in export if you want to go from everyday writing all the way to submission in a single app.
Common pitfalls when converting
- Relative image paths: a relative path such as
gets dropped if the image can’t be found during conversion. Keep your images in the same place relative to your document - Table column widths: Markdown tables have no concept of column width, so you’ll need to adjust them in Word
- Heading levels: decide up front whether
#(H1) is the title in the body text or the document title is kept separately, and your table of contents will come out clean - Line breaks: in standard Markdown, a single newline isn’t treated as a line break. If you’re used to pressing Return to start a new line, an editor that lets you choose this behavior makes things easier