What a crock! How badly documented can a facility be? There are lots of tutorials on the basics of Microsoft Mail Merge, but there is a dearth of information for the INCLUDEPICTURE facility to include images, especially if the images are retrieved from a link/url.

That said, I needed to use it for a project to create a document that plucks up variables from a spreadsheet and drops them into a pretty template for each page. I wrote this note so that the next time I need to revise the document (and stumble over this process), I’ll have these notes. I’m not claiming this is the only way/best way, just that it worked for me. I think I described everything, but please let me know in the comments if I’ve missed something.

I had the following hassles:

• Word uses voodoo magic to accomplish this. [The documentation for how to include images in a mailmerge document is terrible (at least, my google-fu wasn’t strong enough) and it’s worse for images specified by URLs.]
• You need to use (poorly-documented) keyboard commands to type the commands
• Once I had images inserted into the document, I needed to figure out how to adjust their size.

I succeeded – here’s what I did…

1. Create an Excel spreadsheet with links (URLs) to the desired images.
2. The Excel document should have headers in the first row that describe the data. If you’re retrieving images from a website, you’ll need a field with the links.
3. Create a mailmerge document in Word. To do this:
   • New Document, then from the Ribbon:
   • Click the Mailings tab
   • Click Start Mail Merge and choose Letters
   • Click Select Recipients – you’ll need to choose the Excel document (and proper tab) that has the data to be merged
   • Ignore the “Filter recipients…” stuff
4. Click “Insert Merge Field” in the Ribbon and select your fields. The field name appears within «…».
5. They’re voodoo magic. They’re kind of cool. When you click the Preview Results button (in the Ribbon), you’ll see your mail merge results, with substitutions of the live data for your «variables»
6. Click Preview Results again to un-preview results and continue editing the document.

More voodoo magic

1. If you type Alt-F9 Ctl-F9 (Option-Fn-F9 on Mac), the «variables» in the document turn into their underlying representation: «Field1» turns into { MERGEFIELD Field1 } It’s editable text.
2. Don’t do it. It’ll leads to tears. But at least you can see how these are formatted.

Adding an image…

1. If you want to insert an image (say, using a URL from that Excel file) you need to do even more voodoo magic. The format is straightforward, but a bit gnarly: { INCLUDEPICTURE { MERGEFIELD Name-of-URL-Field } * MERGEFORMAT \d }
2. BUT… You can’t just type that string: remember, the { ... } are voodoo magic.
3. Type Alt-F9 (Cmd-F9 on a Mac) to insert an empty set of braces in the document. Then fill in the text between. If you need a new set of braces inside, just type another Alt-F9 (Cmd-F9) in the right place, and keep typing ’til you enter the correct command.
4. Preview Results to see if it’s working.

Resizing an image

1. This is Microsoft Word. So there are no rules. Actually, there are, but they’re not known by mere mortals. (Sorry for the snark.)
2. The images will be any size they want to be.
3. To constrain the images, I found it useful to insert a one-by-one table, and let the content fill the cell. To do this, insert a 1×1 table, and adjust the size of the cell with Table Properties
   • I set the Preferred Width (Table tab)
   • I set “Specify Height” (Row tab)
   • I set “Automatically resize to fit contents” (Options button)
4. I then copy/pasted the voodoo magic for the image into the cell.

Finishing up…

1. OK – You think you’re almost done. Maybe.
2. The Finish and Merge button (in the Ribbon) actually performs the mail merge.
   • Edit Individual Documents seems to create a new Word document containing a concatenation of all the mail-merged pages. You can save this (in Word or PDF format) or print it.
   • Print Documents will print, or let you save to a PDF.
3. You may need to force-load the images, to replace the (single) placeholder image with the right ones. To do this, Select All, then hit F9. You may see a spinner while Word retrieves all the images, but they should all be there.

Additional Thoughts

• I was successful with Microsoft for Mac 2019 using a .docx file, despite the fact that Google brings up a lot of (old) advice about using .doc format, not the (new-fangled) .docx format.
• Keymaps: This article gave me a breakthrough, showing how to insert the voodoo magic { } in a document https://wordmvp.com/Mac/FieldsInMacWord.html
• It’s easiest if the images are all the same size, to minimize resizing effort.
• I think the \d option of the INCLUDEPICTURE command causes Word not to save the images in the document, making the source file considerably smaller.
• I could not find documentation about what the \* MERGEFORMAT string does. It works for me.
• Let me know in the comments if you find find out more. I’ll update this article.

I continue to enjoy using Docker to encapsulate developer tooling so that it doesn’t pollute my laptop with varying versions of software I don’t use regularly. (See Jonathan Bergknoff’s Run More Stuff in Docker and Andrew Welch’s Docker for all the things for further justification.)

In addition to using Andrew Welch’s vitejs-docker-dev project for Javascript development, I converted a couple of my personal projects to use a Dockerfile. I have submitted PRs to the upstream repo’s to incorporate the Dockerfile – we’ll see if they are accepted.

• RPM Test – responsiveness test tool for network latency
• Wireguard Vanity Address – creates a Wireguard public key with an easily-recognizable prefix.
• TrackR-Web-Bluetooth-API – reverse engineering the API for the TrackR Pixel gizmo that helps you find your lost keys
• Unifi-Controller – Instructions for a pre-built Docker container that runs on a Raspberry Pi

TL;DR Using a Docker container for these tools doesn’t really get in the way. Startup may be slightly slower (adding a second or so), but otherwise these tools run plenty fast. Plus, Docker eliminates a whole raft of hassles getting the software installed, and maintaining it across OS upgrades (say, on my laptop). I’m content.

Update: I am now contributing to the PRQL project. They have a highly-developed Docker container that encapsulates the build tools which mean that all the versions of Rust, Javascript, and other tools are isolated from my host operating system.