How to edit template partials for docx format?

[achetverikov]

I was hoping to customize the docx template a bit (add words "Abstract" and "References" before the corresponding sections, make some other small changes...). I see examples for html/pdf here https://quarto.org/docs/journals/templates.html#html-partials but not for docx and the docx folder here https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats has images only. How to edit template partials for docx format? Are there any examples of customized article templates using docx available?

[cscheid]

I see examples for html/pdf here http://nipype.readthedocs.io/en/latest/documentation.html

(This is a broken link, at least for me; I wonder if you have a typo)

---

What you're trying to achieve is probably easier to do with a custom Lua filter that processes the document and adds those words to the right headings. Have you considered that route first?

[achetverikov]

I wonder how that link got here, I meant this one https://quarto.org/docs/journals/templates.html#html-partials (edited the question now to fix the link). No, I haven't considered using Lua for that. Could you give an example of how to do this?

[cscheid]

It's a bit of a learning curve, but we have some pointers here: https://quarto.org/docs/extensions/filters.html#development

[achetverikov]

thanks, I'll look into it! But going back to the original question: is there no easy way to edit the structure of the generated docx file through templates as you would do with tex?

[cscheid]

The thing is that "templates" mean something slightly different than what you're expecting, because Pandoc templates (roughly speaking) allow a limited amount of formatted inclusion. In LaTeX, "templates"can call arbitrary commands etc (because LaTeX itself is a programming language, and latex code is just source). In Pandoc, templates are textual, and so you can't easily use formatted or structured input. If you want to (eg) add a section or a reference heading, the solution really needs to go through Lua.

[achetverikov]

thanks, got it!

[cderv]

@achetverikov to add to Carlos answer regarding

is there no easy way to edit the structure of the generated docx file through templates as you would do with tex?

Pandoc does not have text template for Docx. To cite the documentation

docx and pptx have no template (however, you can use --reference-doc to customize the output).

This is why you can't find the same partial template feature in Quarto as for HTML or TeX.

For PPTX and DOCX, it is using a reference document. Quarto is leveraging this reference doc feature for word templating : https://quarto.org/docs/output-formats/ms-word-templates.html
However, this is mainly useful to customize styling of the output - default and custom styles

For the adding content automatically or based on some metadata, Lua filter will be the way.

Just sharing that in case you did not know about reference docs.

[multimeric]

Thanks for this answer. Can you elaborate on how Quarto does the docx export and how we can extend it though? If the docx templates are only used for styling and there is no other templating mechanism, then why does my docx output have a different title page from my html output? Where is this defined in Quarto, and how can I modify it using a filter/format?

[cderv]

Can you elaborate on how Quarto does the docx export and how we can extend it though?

Quarto uses Pandoc to convert to Docx (https://pandoc.org/MANUAL.html) and the templating mechanism is from Pandoc (https://pandoc.org/MANUAL.html#option--reference-doc) - this is different than Pandoc's template logic (https://pandoc.org/MANUAL.html#templates). Doc even says: "docx and pptx have no template (however, you can use --reference-doc to customize the output)."

If the docx templates are only used for styling and there is no other templating mechanism, then does my docx output have a different title page from my html output?

Yes I believe it does. Pandoc does write the Docx using the template directly in Haskell in its writer (https://github.com/jgm/pandoc/blob/main/src/Text/Pandoc/Writers/Docx.hs) - it is not using the same templating logic as for other format (https://pandoc.org/MANUAL.html#templates). If you look at the writer you can see it is writing directly OpenXml syntax for docx and modifying / creating xml format.

Where is this defined in Quarto, and how can I modify it using a filter/format?

What you can do in a Lua filter is catched some AST node and decide to write some raw openxml string directly instead of letting Pandoc writer convert this node. For example would do this for some post processing like Callout feature from Quarto (in https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/filters/quarto-post/docx.lua)

So for now, Quarto capabilities for Docx output is quite tied by Pandoc support. Some other tools in other language are for example post processing Pandoc output by modifying the docx produced (like officedown for R users), or tools like officer for R users allows to read a docx and tweak it before writing it back. Same type of tools exist in Python world like python-docx.

Hope it helps understand the current situation.

[multimeric]

Wonderful, thanks for this answer! The example you link of adding raw XML via lua is the best example I've seen of something like this, because I can see how a Quarto extension might do the same.