Mail merge with DOCX templates: why {{fields}} break and how to fix (2026)
A placeholder like {{FirstName}} that looks whole in Word is often stored as two or three separate pieces of text inside the file, for example {{First and Name}}, because Word starts a new "run" each time formatting, spell-check state or editing history changes. A find-and-replace on the raw XML then finds nothing. The fix is to join the text of all runs in a paragraph, replace the placeholder, and put the result back into the first run, which is what template engines and this tool do.
What a run is
A .docx is a ZIP file; the text is in word/document.xml. Microsoft's Open XML documentation (Working with runs) quotes the ISO/IEC 29500 standard: a run "defines a region of text with a common set of properties", it is the r element, and the text itself sits in t elements inside it.
A placeholder typed in one go usually stays in one run:
<w:r><w:t>Dear {{FirstName}},</w:t></w:r>After an edit, a spell-check pass or a formatting change, the same text can become:
<w:r><w:t>Dear {{First</w:t></w:r>
<w:proofErr w:type="spellStart"/>
<w:r><w:rPr><w:b/></w:rPr><w:t>Name}}</w:t></w:r>Common causes
| Cause | What happens in the XML | How to avoid it in Word |
|---|---|---|
| Spelling or grammar marks | w:proofErr elements split the word | Type the field, then mark it "Do not check spelling" or ignore the error |
| Partial formatting | Bold only on part of the field creates a second run | Format the whole field at once |
| Editing history (revision IDs) | Text typed in two sessions gets two runs | Retype the whole field in one go |
| Tracked changes | Insertions are wrapped in w:ins | Accept all changes before merging |
How to check a template
- Rename a copy of the file from
.docxto.zipand openword/document.xml. - Search for
{{. If the closing}}is not in the same<w:t>element, the field is split.
Or drop the template into the DOCX mail merge tool: it lists every field it found after joining the runs, so a split field still appears whole, and any field that does not match a spreadsheet column is reported before download.
How the merge handles it
For each paragraph, the tool:
- reads the text of every
<w:t>in order, ignoringw:proofErr, bookmarks and other markers, - finds each
{{...}}in the joined text, - moves the complete placeholder into the text element where it starts, which keeps that run's formatting, and removes the moved characters from the following elements,
- replaces the placeholder with the escaped value; line breaks in a cell become
<w:br/>.
It never joins text across paragraphs. It processes the body, headers, footers, footnotes and endnotes.
Classic Word merge fields («FirstName»)
Templates built with Word's own mail merge contain MERGEFIELD field codes instead of braces. The tool converts simple MERGEFIELD codes to company being registered in France before merging and removes the link to the data source in word/settings.xml, so the output files open without Word asking to run the data-source query. Fields nested inside IF fields are left as they are.
FAQ
Will my formatting survive? Yes. Only the text inside <w:t> elements changes; styles, tables, images, headers and page layout are copied unchanged. The replaced value takes the formatting of the first character of the placeholder.
Can a field span two lines? Not across paragraphs. A {{ in one paragraph and }} in the next is left untouched.
Does it convert the .docx to PDF? No. Open the generated files in Word and use Save As PDF, or use the built-in PDF template of the same tool.
Is my document uploaded? No. The .docx is unzipped, filled and re-zipped in the browser.