Problem statement

I am creating a custom OpenXML template to compile Pandoc's Markdown into DOCX, where the specific DOCX layout is provided by the template. In this template, I want to include some images.

How images are included in DOCX/OpenXML

In other template formats (such as HTML or LaTeX) including an image would be trivial, however for DOCX this is not so straighforward due to the way images are handled. To include an image in OpenXML, the OpenXML references an rId (in /word/document.xml). This rId is then linked to the image file (which resides in /word/media/) via a mapping defined in /word/_rels/document.xml.rels.

What I have tried

If I provide a reference-doc.docx which contains the images in question via the --reference-doc option, I noticed that those images are included in the compiled document under /word/media/, even if they are not actually used in the document. This gets me half of the way there, as the images are now available to the compiled document. However, I have no way of creating corresponding rIds for these image files, as I haven't found a way to influence the contents of /word/_rels/document.xml.rels in the compiled document.

On second thought, it looks like pandoc preserves the header and footer from reference-doc.docx. One solution might be to insert the images into the headers, make them 100% transparent so they are not visible, and then use the rIds of those images in the OpenXML template. While this might work, it doesn't seem very elegant as the compiled document would end up with a header which contains a bunch of transparent images!

I'd be keen to hear if someone has better ideas. Perhaps there is some other way to preserve the rIds defined in reference-doc.docx so that they can be used in the OpenXML template? Thanks in advance for your help!