% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/printers.R
\name{repair_docx}
\alias{repair_docx}
\title{Repair flextables in a 'Word' document produced by 'pandoc'}
\usage{
repair_docx(path, target = path)
}
\arguments{
\item{path}{path of the 'docx' file to repair. The file is modified
in place unless \code{target} is provided.}

\item{target}{path of the resulting 'docx' file. Defaults to \code{path}.}
}
\value{
the path of the repaired file, invisibly.
}
\description{
Word documents produced by Quarto (\code{format: docx}) or by
\code{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 \strong{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
\code{officer::block_pour_docx()}).

It is not needed when the document is produced with
\code{officedown::rdocx_document()} or \code{\link[=save_as_docx]{save_as_docx()}}, where the file is
already written by 'officer'.
}
\section{What to do with Quarto}{


The repair must run after \verb{quarto render}. Quarto can do it for you
with a \emph{post-render script}, but this can \strong{only} be declared in a
\verb{_quarto.yml} file - the \verb{project:} key is ignored in the YAML header
of a \code{.qmd} file.
\enumerate{
\item Next to your \code{.qmd} file, create a file \verb{_quarto.yml} containing:
}

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{project:
  post-render: repair.R
}\if{html}{\out{</div>}}
\enumerate{
\item In the same directory, create the file \code{repair.R} containing:
}

\if{html}{\out{<div class="sourceCode r">}}\preformatted{files <- strsplit(Sys.getenv("QUARTO_PROJECT_OUTPUT_FILES"), "\\n")[[1]]
for (f in files[grepl("\\\\.docx$", files, ignore.case = TRUE)]) \{
  flextable::repair_docx(f)
\}
}\if{html}{\out{</div>}}
\enumerate{
\item Render as usual, either the whole project (\verb{quarto render}) or a
single file (\verb{quarto render doc.qmd}); the script runs in both cases
and only processes the files that were rendered.
}

Without a \verb{_quarto.yml}, call \code{repair_docx("doc.docx")} manually
after each render.
}

\section{What to do with R Markdown}{


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

\section{Requirements and limits}{

\itemize{
\item The images referenced in the document must still exist, at paths
resolvable \strong{from the directory where \code{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. \code{here::here()}) in that case.
\item Mini graphics generated by \code{\link[=minibar]{minibar()}}, \code{\link[=linerange]{linerange()}},
\code{\link[=gg_chunk]{gg_chunk()}}, \code{\link[=plot_chunk]{plot_chunk()}} and \code{\link[=grid_chunk]{grid_chunk()}} are written to
temporary 'PNG' files that no longer exist once rendering has
completed: \strong{these can not be repaired afterwards}. With Quarto or
\code{rmarkdown::word_document()}, use image files you manage yourself
(\code{\link[=as_image]{as_image()}}, \code{\link[=colformat_image]{colformat_image()}}); mini graphics require
\code{officedown::rdocx_document()} or \code{\link[=save_as_docx]{save_as_docx()}}.
\item When a referenced image can not be found, the rewrite fails with
an error \verb{cannot open the connection} and a warning naming the
missing file.
}
}

\examples{
\dontrun{
repair_docx("document.docx")
}
}
\seealso{
Other functions for flextable output and export:
\code{\link[=df_printer]{df_printer()}},
\code{\link[=flextable_to_rmd]{flextable_to_rmd()}},
\code{\link[=gen_grob]{gen_grob()}},
\code{\link[=htmltools_value]{htmltools_value()}},
\code{\link[=knit_print.flextable]{knit_print.flextable()}},
\code{\link[=plot.flextable]{plot.flextable()}},
\code{\link[=print.flextable]{print.flextable()}},
\code{\link[=save_as_docx]{save_as_docx()}},
\code{\link[=save_as_html]{save_as_html()}},
\code{\link[=save_as_image]{save_as_image()}},
\code{\link[=save_as_pptx]{save_as_pptx()}},
\code{\link[=save_as_rtf]{save_as_rtf()}},
\code{\link[=to_html.flextable]{to_html.flextable()}},
\code{\link[=wrap_flextable]{wrap_flextable()}}
}
\concept{flextable_output_export}
