The Quiet Alchemy of Pandoc: Converting Between Word and Markdown
Table of Contents
- The Problem No One Talks About
- Meet Pandoc: The Rosetta Stone of Documents
- Pandoc Markdown: The Supercharged Dialect
- The Reference Docx: Your Styling Talisman
- Creating Your Own Reference Docx
- Pro Tip: Extract Pandoc’s Default
- The Reverse Journey: .docx → .md
- Preserving More with --wrap=preserve
- A Workflow for Both Worlds
- The Deeper Lesson
There are two kinds of writers in this world: those who live inside Microsoft Word, and those who live inside plain text.
I’ve spent years straddling this divide, and I can tell you—it’s not a comfortable place to stand. On one side, the warmth of WYSIWYG comfort: bold buttons, font drop-downs, margin rulers, and the satisfying thump of a printed page. On the other, the stark purity of Markdown: no formatting chrome, no hidden XML, just text and the occasional # or ** to mark meaning. 🏔️
For the longest time, I thought these two worlds were fundamentally irreconcilable. That to work in one meant abandoning the other. Then I discovered Pandoc—and realized the bridge had been there all along.
The Problem No One Talks About
Here’s the thing about document formats: they’re not just files. They’re interfaces between how you think and what the machine understands.
.docx is a rendered page. It cares about where text sits on paper. It remembers that you used 14pt Calibri for that heading and that the paragraph spacing should be exactly 12 points after. It’s a snapshot of presentation.
Markdown is a semantic tree. It cares about what things are. This is a heading, this is a list, this is an emphasized word. It doesn’t know or care about fonts. It’s an expression of meaning.
When you convert between them, you’re not just changing file extensions. You’re translating between two entirely different philosophies of representation. Think of it like translating between Chinese and Arabic—both encode language, but the symbols, grammar, and assumptions about the reader are profoundly different.
This is where most conversion tools fail. They treat the problem as a mechanical mapping: “this bold text becomes **bold**”. But real conversion requires understanding the intent behind the formatting—distinguishing a Heading 1 used as a chapter title from a Heading 1 used as a section divider. That’s hard. And that’s what makes Pandoc special.
Meet Pandoc: The Rosetta Stone of Documents
Pandoc, created by philosopher-programmer John MacFarlane, is a command-line tool that converts documents between virtually every markup format under the sun. Markdown, HTML, LaTeX, docx, EPUB, PDF, reStructuredText, AsciiDoc—the list goes on. It’s been called the “Swiss Army knife” of document conversion, but I think it’s more like a universal translator from a sci-fi novel.
# The basic incantation looks deceptively simple:
pandoc input.docx -t markdown -o output.md
pandoc input.md -t docx -o output.docxTwo lines. That’s it. Underneath, though, an entire symphony is playing.
Pandoc works by converting everything into its own internal abstract syntax tree (AST)—a kind of universal document DNA. It reads your source format, builds this AST, then serializes it into the target format. This two-step process is what makes Pandoc so faithful: it’s not guessing at a direct mapping; it’s reconstructing the document’s meaning and then re-rendering it.
Pandoc Markdown: The Supercharged Dialect
Standard Markdown is a lovely minimal language, but it was designed for web writing—simple lists, links, a heading here and there. When you try to represent a real-world document (with footnotes, tables, figure captions, cross-references), standard Markdown chokes. 🤷
This is where Pandoc’s extended Markdown comes in. It’s the same familiar syntax, but with superpowers bolted on:
# Footnotes that actually work
Here's a sentence with a footnote.[^1]
[^1]: And here is the footnote text, which Pandoc will place at the bottom of the page.
# Tables that don't make you cry
| Left | Center | Right |
|---------|:--------:|--------:|
| Cell | Cell | Cell |
# Definition lists
Term One
: Definition for term one
# Fenced divs for arbitrary blocks
::: {.callout-note}
This is a note block with custom styling.
:::
# Strikeout, superscript, subscript
This is ~~deleted~~, H~2~O, and 2^10^.
# YAML metadata blocks
---
title: 'My Document'
author: 'Me'
---
These extensions aren’t just conveniences. They’re the essential vocabulary that bridges Markdown’s semantic simplicity with the richness of a Word document. A footnote in Pandoc Markdown—[^1]—is not just text with a superscript number. It’s a semantic annotation that Pandoc can faithfully render as a real Word footnote in .docx, or as an HTML <sup> in a webpage.
The brilliance is that Pandoc Markdown is additive. You can stick to plain CommonMark if you like, and your document remains perfectly readable. But when you need a definition list or a fenced div, the syntax is there, waiting.
The Reference Docx: Your Styling Talisman
Now, here’s where things get really interesting. 🧪
When you convert Markdown to .docx, Pandoc produces a perfectly valid Word document. But it’s ugly. The default styles are functional but soulless—like a hotel room that technically has all the amenities but none of the character.
The solution is the reference document.
pandoc input.md -t docx --reference-doc=my-styles.docx -o output.docxA reference docx is a regular Word file that serves as a style blueprint. Pandoc reads it, extracts the style definitions, and applies them to your output. The heading fonts, the colors, the paragraph spacing, the page margins, the footnote formatting—everything flows from the reference.
Here’s the part that blew my mind: the reference docx doesn’t need any content. It can be an empty Word file with nothing but styles defined. Think of it like a CSS file for Word—a separate layer of presentation that you can swap, version, and reuse across projects.
Creating Your Own Reference Docx
- Create a new, empty .docx file (use Word, LibreOffice, or even Pandoc itself).
- Modify the styles to match your preferences. Set Heading 1 to your favorite font and color. Adjust Normal paragraph spacing. Configure page margins. Set up headers and footers.
- Save it as
reference.docxsomewhere in your project.
That’s it. Now every Markdown-to-Word conversion through Pandoc will produce a document that looks like it was hand-crafted in Word—because it effectively was, using your styles as the mold.
The styles that matter most are the ones Pandoc actually uses:
- Normal — base paragraph text
- Heading 1, 2, 3, 4, 5, 6 — section headings
- Title — the document title (from YAML metadata)
- Author — the author field
- Abstract — for abstract blocks
- Code / CodeBlock — inline and block code
- BlockQuote — block quotes
- Footnote Text — footnote content
- Table / Table Header — table styles
- Caption — figure/table captions
- Image Caption — image figure text
- Header / Footer — page header/footer
- TOC Heading — if using a table of contents
A well-crafted reference docx is like a secret handshake between Pandoc and Word. It tells the converter: “Don’t guess what I want. This is what I want.”
Pro Tip: Extract Pandoc’s Default
Pandoc ships with a built-in default reference docx. You can extract it, customize it, and use your version:
pandoc -o custom-reference.docx --print-default-data-file reference.docx
# Then open custom-reference.docx in Word, modify styles, save.
pandoc input.md -t docx --reference-doc=custom-reference.docx -o output.docxThis is one of those rare cases where reading the defaults is actually the best place to start. Modify what matters, leave the rest, and you’re done.
The Reverse Journey: .docx → .md
Going the other direction—Word to Markdown—is where Pandoc truly earns its keep. 🧭
pandoc report.docx -t markdown -o report.mdWhat comes out is a remarkably clean Markdown file. Headings become #, ##, etc. Bold and italic are represented with ** and *. Lists are properly nested. Images are extracted (or referenced). Tables become pipe tables.
But there are quirks worth knowing:
- Track changes are not converted. Accept or reject changes before conversion.
- Comments are lost. Extract them separately if needed.
- Complex layouts (multi-column, text boxes, floating images) may not survive intact. Word lets you place things arbitrarily on a page; Markdown doesn’t have a concept of “absolute position.”
- Cross-references (like “see Figure 3”) become plain text. Pandoc can’t know the target numbering in Markdown.
Yet for 90% of real-world documents—reports, essays, articles, documentation—the conversion is astonishingly good. I’ve converted 100-page .docx manuscripts and gotten back Markdown that needed only minor cleanup.
Preserving More with --wrap=preserve
By default, Pandoc re-wraps paragraphs. If you want to preserve the original line breaks:
pandoc input.docx -t markdown --wrap=preserve -o output.mdA Workflow for Both Worlds
Here’s where the magic becomes practical. 🪄
I work in pure Markdown for drafting. It lives in Git, renders beautifully in VS Code, and doesn’t distract me with fonts and margins. I use Pandoc Markdown for all the richness I need (footnotes, tables, citations).
When I need to send a document to someone who lives in Word, I run:
pandoc draft.md -t docx --reference-doc=company-template.docx -o final.docxWhen someone sends me a Word document that I need to edit or incorporate, I run:
pandoc received.docx -t markdown --wrap=preserve -o draft.mdThis two-way bridge has fundamentally changed how I work. I don’t need to choose between ecosystems anymore. I can live in plain text and visit Word when needed—or vice versa.
The deeper lesson is that formats are not prisons. They are interfaces with different affordances. Markdown is optimized for writing and version control. .docx is optimized for presentation and collaboration with non-technical users. By learning to move fluidly between them, you gain the strengths of both without being locked into either.
The Deeper Lesson
Every format conversion is a small act of translation. And like all translation, it’s never perfect—but it can be revelatory.
What does it mean that a Word heading “looks like” a heading, while a Markdown heading “declares itself” as one? What does it reveal about how we think about documents—as visual artifacts or as semantic structures?
I think about this every time I run Pandoc. The quiet alchemy happening in the terminal—parsing, transforming, rebuilding—isn’t just file conversion. It’s a meditation on the relationship between form and meaning. A .docx and a .md can represent the same words, but they encode fundamentally different ideas about what a document is.
Pandoc gives us a bridge. The rest is up to us—and how we choose to write. 🖋️
Pandoc is free and open-source. Install it at pandoc.org or via your package manager (brew install pandoc on macOS).