8.2 The two-way workflow between R Markdown and Word

While it is easy to generate a Word document from R Markdown, things can be particularly painful when someone else edits the Word document and you have to manually port the changes back to the original R Markdown document. Luckily, Noam Ross has provided a promising solution to this problem. The redoc package (https://github.com/noamross/redoc) allows you to generate a Word document, revise the Word document, and convert the revised Word document back to R Markdown. Please note that as of this writing (June 2020), the redoc package is still experimental, and more unfortunately, its author has suspended the development. Anyway, if you want to try it out, you can install the package from GitHub:

  1. remotes::install_github("noamross/redoc")

Once the package is installed, you may use the output format redoc::redoc:

  1. ---
  2. output: redoc::redoc
  3. ---

This output format generates a Word document that actually stores the original Rmd document, so the Word document can be converted back to Rmd. Tracked changes in Word will be converted to text written with the CriticMarkup syntax (http://criticmarkup.com). For example, {++ important ++} represents the insertion of the word “important” in the text.

You can convert the Word document generated by redoc::redoc to Rmd via the function redoc::dedoc(), e.g., redoc::dedoc("file.docx") will generate file.Rmd. In this process, you can decide how to deal with tracked changes in Word via the track_changes argument, e.g., you may accept or reject changes, or convert tracked changes to CriticMarkup. We recommend that you use track_changes = 'criticmarkup' to avoid the permanent loss of tracked changes.

When editing the Word document, you are expected to edit the parts that are not automatically generated by code chunks or inline R expressions in R Markdown. For example, you must not edit a table if it is automatically generated by knitr::kable() in a code chunk, because such changes will be lost when you convert Word to Rmd via dedoc(). To avoid accidentally editing the automatic results from code chunks, you may set the option highlight_outputs to true in the redoc::redoc format, which means the automatic output will be highlighted in Word (with a background color). You should tell your collaborator that they should not touch these highlighted parts in the Word document.

Again, the redoc package is still experimental and its future is unclear at the moment, so the introduction here is intentionally brief. When in doubt, we recommend that you read its documentation on GitHub.