knitr/Rmd: Adding title page and text when converting to MS Word

Question

I'm trying to write a report using the rmarkdown package and as it is, unfortunately, customary in my field reports are often submitted as MS Word documents. So I can't always rely on the power of LaTeX and have to be able convert my .Rmd to MS Word. Now, because I want to be able to create PDF and MS Word files from the same source file, I'm trying to find a general way to do this. I've got PDF working using the apa6 LaTeX-document class. The .Rmd will look something like this when creating a Word file:

---
title: My title
abstract: This is the abstract.
author: John Doe
affiliation: Unknown
note: Nothing to say.

output:
  word_document:
    reference_docx: myreference.docx
---

Lorem ipsum.

I can create a Word document from this but for obvious reasons my custom yaml-variables (e.g. abstract) will not be rendered in the document.

So basically, my problem is the following:

When creating a word document, how can I add a title page (including author names, affiliations, author notes, etc.) and another page with just the abstract before the document body ("Lorem ipsum")? The focus here is not to create pagebreaks (there are other open questions on this), but rather **is there a way to make pandoc use the custom yaml variables place them at the beginning of the document and assign styles to them?

The rmarkdown package provides an include() function but it only works with HTML and PDF documents.

Answer 1

I have found that it's possible to customize the content of the Markdown file (e.g. to add and modify a title page) generated by rmarkdown before submitting it to pandoc for the conversion to DOCX by using a preprocessor. Let's assume we are trying to add some information specified in a YAML parameter note just before the abstract (support for abstracts has in the meantime been added to pandoc).

To do so, we first need a preprocessor function that reads the input file and parses the YAML front matter, and customizes the input file:

my_pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir, from) {

  # Identify YAML front matter delimiters
  input_text <- readLines(input_file, encoding = "UTF-8")
  yaml_delimiters <- grep("^(---|\\.\\.\\.)\\s*$", input_text)

  if(length(yaml_delimiters) >= 2 &&
     (yaml_delimiters[2] - yaml_delimiters[1] > 1) &&
     grepl("^---\\s*$", input_text[yaml_delimiters[1]])) {
    yaml_params <- yaml::yaml.load(paste(input_text[(yaml_delimiters[1] + 1):(yaml_delimiters[2] - 1)], collapse = "\n"))
  } else yaml_params <- NULL

  # Modify title page
  custom_lines <- c(
    "NOTE:"
    , metadata$note
    , "\n\n"
    , "# Abstract"
    , "\n"
    , metadata$abstract
    , "\n"
  )

  ## Add modified title page components after YAML front matter
  augmented_input_text <- c(custom_lines, input_text[(yaml_delimiters[2] + 1):length(input_text)])

  # Remove redundant default abstract
  yaml_params$abstract <- NULL

  # Add modifications to input file
  augmented_input_text <- c("---", yaml::as.yaml(yaml_params), "---", augmented_input_text)
  input_file_connection <- file(input_file, encoding = "UTF-8")
  writeLines(augmented_input_text, input_file_connection)
  close(input_file_connection)

  NULL
}

Now we need to define a custom format that utilizes our preprocessor:

my_word_document <- function(...) {
  config <- rmarkdown::word_document(...)

  # Preprocessor functions are adaptations from the RMarkdown package
  # (https://github.com/rstudio/rmarkdown/blob/master/R/pdf_document.R)
  pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir, output_dir, from = .from) {
    # save files dir (for generating intermediates)
    saved_files_dir <<- files_dir

    args <- my_pre_processor(metadata, input_file, runtime, knit_meta, files_dir, output_dir, from)
    args
  }

  config$pre_processor <- pre_processor
  config
}

Now, you can use the custom format when rendering R Markdown documents as follows:

rmarkdown::render("./foo/bar.Rmd", output_format = my_word_document())