Building a Pandoc reference.docx: Markdown to branded Word
Markdown gives you a clean source of truth, but sooner or later someone asks for a Word file that looks like your company actually made it: house fonts, branded headings, consistent margins. Pandoc solves this with a single file called a reference docx. Every style in the exported document — headings, body text, tables, footnotes — is inherited from that file, so building a good one is the difference between a generic dump and a document that ships.
This article walks through how a reference docx works, how to produce one, which styles deserve your attention, and how to test the result without going in circles. The ideas apply whether you convert on the command line or in the browser — and a finished reference docx plugs straight into Pandoc's --reference-doc flag.
Why the reference docx decides everything
When Pandoc writes a docx file, it does not copy the layout of your Markdown. It generates a fresh document and attaches named styles to every element: Heading 1 for top-level sections, Body Text for ordinary paragraphs, Table Caption for captions. Word then decides what those styles look like — and the definitions come from the reference docx you supplied.
The content of the reference file itself is ignored. Only its styles and its document properties matter: page size, margins, header and footer, even the default language. That separation is what makes the system stable. You never edit generated output by hand; you edit the template once, and every future conversion picks the change up automatically.
Producing your first template
There are two practical starting points. The first is to let Pandoc print its own default template: run pandoc with the --print-default-data-file reference.docx argument and save the output as a file such as custom-reference.docx. Open it in Word, modify the styles you care about, and save. Because you started from Pandoc's own file, every style the writer can use is already present and correctly named.
The second route starts from real output. Convert a representative Markdown document to docx first, then open the result and restyle it directly. This keeps you honest, because you are editing exactly the structure your readers will see, including the quirks of your actual content rather than an abstract sample.
The styles that matter most
Start with the heading ladder. Heading 1 through Heading 6 set the tone of the whole document, so adjust font, size, spacing and numbering there first. Title, Subtitle, Author and Date style the title block that appears when your Markdown carries YAML front matter with those fields. Body Text governs ordinary paragraphs, and First Paragraph lets you treat the paragraph after a heading differently — a common typography trick for dropping the indent.
Do not overlook Compact, the style Pandoc applies to tight lists. If your lists look cramped or over-spaced, that is the style to fix. Setting these few styles covers most of what a reader notices on any given page, and none of them require touching Word's more exotic dialogs.
Tables, footnotes and captions
Tables are styled through the Table style, which controls borders, cell padding and header-row shading. Word's table style editor is fiddly, so expect to spend more time here than on the headings. The payoff is that every converted table inherits consistent rules instead of whatever bare defaults the writer ships with.
Footnote Text controls the note body at the bottom of the page, while Footnote Reference styles the superscript marker in the running text. Image Caption and Table Caption handle the captions Pandoc attaches to figures and tables respectively. Style them once and long documents stay consistent from the first chapter to the last appendix.
Code blocks and math
Code blocks land in the Source Code style, with inline code wrapped in Verbatim Char. Give Source Code a monospaced font, a light background shading and sensible line spacing, and technical documents instantly look intentional. Syntax highlighting colours, where enabled, are applied on top of the style, so the base formatting survives regardless of highlight theme.
Math takes a different path entirely. Pandoc converts TeX notation into Word's native OMML equation format, so formulas arrive as real, editable equations rather than pictures. Their appearance follows the document's math font, which Word defaults to Cambria Math. You rarely need to restyle anything here; just be aware that equations live outside the paragraph-style system.
Using your template and closing the loop
On the command line the whole loop is one flag: pandoc --reference-doc=custom-reference.docx input.md -o output.docx. This site's Markdown to Word export currently relies on Pandoc's built-in styles, and its Pro template option accepts a Pandoc text template for Markdown, HTML, RST and LaTeX output — so for branded docx, the reference docx plus the CLI flag is the reliable path today.
Make testing a loop rather than an event. Edit one or two styles, reconvert the same sample document, and compare against the previous output. Iterating with a small, representative file — two heading levels, a table, a footnote and one code block — surfaces problems in seconds and keeps you from restyling blind.
Handing the template to editors and publishers
The finished reference docx is a small, self-contained artefact that encodes your entire visual identity: fonts, margins, headers, footers, heading colours. Store it next to your content in version control, name it clearly, and any team member can regenerate on-brand Word files from Markdown without touching Word's style dialogs.
Editors and publishers benefit too, because the document arrives with real named styles rather than direct formatting, so their own templates can remap or override anything downstream. One Markdown source and one template file can then serve a website, a PDF pipeline and a Word deliverable without manual reformatting.