Skip to contents

Repair flextables in a 'Word' document produced by 'pandoc'

Source: R/printers.R
repair_docx.Rd

Word documents produced by Quarto (format: docx) or by rmarkdown::word_document() are written by 'pandoc', which copies the raw OOXML of flextable objects verbatim: images and hyperlinks are left as unresolved references (file paths and URLs instead of relationship identifiers) and Word refuses to open the file.

This function reads such a document and rewrites it with the package 'officer', whose writer resolves these references: images and SVG files are embedded, hyperlinks are registered, and the other officer-flavored contents are processed as well (sections, footnotes, comments, custom style names, list markers, documents poured with officer::block_pour_docx()).

It is not needed when the document is produced with officedown::rdocx_document() or save_as_docx(), where the file is already written by 'officer'.

Usage

repair_docx(path, target = path)

Arguments

path

path of the 'docx' file to repair. The file is modified in place unless target is provided.

target

path of the resulting 'docx' file. Defaults to path.

Value

the path of the repaired file, invisibly.

What to do with Quarto

The repair must run after quarto render. Quarto can do it for you with a post-render script, but this can only be declared in a _quarto.yml file - the project: key is ignored in the YAML header of a .qmd file.

  1. Next to your .qmd file, create a file _quarto.yml containing:

project:
  post-render: repair.R

  1. In the same directory, create the file repair.R containing:

files <- strsplit(Sys.getenv("QUARTO_PROJECT_OUTPUT_FILES"), "\n")[[1]]
for (f in files[grepl("\\.docx$", files, ignore.case = TRUE)]) {
  flextable::repair_docx(f)
}

  1. Render as usual, either the whole project (quarto render) or a single file (quarto render doc.qmd); the script runs in both cases and only processes the files that were rendered.

Without a _quarto.yml, call repair_docx("doc.docx") manually after each render.

What to do with R Markdown

Prefer officedown::rdocx_document() as output format: the file is post-processed by 'officer' and no repair is needed. With rmarkdown::word_document(), call repair_docx() on the output file after rmarkdown::render().

Requirements and limits

  • The images referenced in the document must still exist, at paths resolvable from the directory where repair_docx() runs: a Quarto post-render script runs at the project root, so images referenced with paths relative to a sub-directory document will not be found - use absolute paths (e.g. here::here()) in that case.

  • Mini graphics generated by minibar(), linerange(), gg_chunk(), plot_chunk() and grid_chunk() are written to temporary 'PNG' files that no longer exist once rendering has completed: these can not be repaired afterwards. With Quarto or rmarkdown::word_document(), use image files you manage yourself (as_image(), colformat_image()); mini graphics require officedown::rdocx_document() or save_as_docx().

  • When a referenced image can not be found, the rewrite fails with an error cannot open the connection and a warning naming the missing file.

See also

Other functions for flextable output and export: df_printer(), flextable_to_rmd(), gen_grob(), htmltools_value(), knit_print.flextable(), plot.flextable(), print.flextable(), save_as_docx(), save_as_html(), save_as_image(), save_as_pptx(), save_as_rtf(), to_html.flextable(), wrap_flextable()

Examples

if (FALSE) { # \dontrun{
repair_docx("document.docx")
} # }