officedown (version 0.2.2)

rdocx_document: Advanced R Markdown Word Format

Description

Format for converting from R Markdown to an MS Word document. The function comes also with improved output options.

Usage

rdocx_document(
  base_format = "rmarkdown::word_document",
  tables = list(),
  plots = list(),
  lists = list(),
  mapstyles = list(),
  page_size = list(),
  page_margins = list(),
  reference_num = TRUE,
  ...
)

Arguments

base_format

a scalar character, format to be used as a base document for officedown. default to word_document but can also be word_document2 from bookdown.

When the base_format used is bookdown::word_document2, the number_sections parameter is automatically set to FALSE. Indeed, if you want numbered titles, you are asked to use a Word document template with auto-numbered titles (the title styles of the default `rdocx_document' template are already set to FALSE).

tables

a list that can contain few items to style tables and table captions. Missing items will be replaced by default values. Possible items are the following:

• style: the Word stylename to use for tables.

• layout: 'autofit' or 'fixed' algorithm. See table_layout.

• width: value of the preferred width of the table in percent (base 1).

• caption; caption options, i.e.:

  • style: Word stylename to use for table captions.

  • pre: prefix for numbering chunk (default to "Table ").

  • sep: suffix for numbering chunk (default to ": ").

• conditional: a list of named logical values:

  • first_row and last_row: apply or remove formatting from the first or last row in the table

  • first_column and last_column: apply or remove formatting from the first or last column in the table

  • no_hband and no_vband: don't display odd and even rows or columns with alternating shading for ease of reading.

Default value is (in R format):

list(
   style = "Table", layout = "autofit", width = 1,
   caption = list(
     style = "Table Caption", pre = "Table ", sep = ": "),
   conditional = list(
     first_row = TRUE, first_column = FALSE, last_row = FALSE,
     last_column = FALSE, no_hband = FALSE, no_vband = TRUE
   )
)

Default value is (in YAML format):

style: Table
layout: autofit
width: 1.0
caption:
  style: Table Caption
  pre: 'Table '
  sep: ': '
conditional:
  first_row: true
  first_column: false
  last_row: false
  last_column: false
  no_hband: false
  no_vband: true

plots

a list that can contain few items to style figures and figure captions. Missing items will be replaced by default values. Possible items are the following:

• style: the Word stylename to use for plots.

• align: alignment of figures in the output document (possible values are 'left', 'right' and 'center').

• topcaption: caption will appear before (on top of) the figure,

• caption; caption options, i.e.:

  • style: Word stylename to use for figure captions.

  • pre: prefix for numbering chunk (default to "Figure ").

  • sep: suffix for numbering chunk (default to ": ").

Default value is (in R format):

list(
  style = "Normal", align = "center", topcaption = FALSE,
  caption = list(
    style = "Image Caption",
    pre = "Figure ",
    sep = ": "
   )
 )

Default value is (in YAML format):

style: Normal
align: center
topcaption: false
caption:
  style: Image Caption
  pre: 'Figure '
  sep: ': '

lists

a list containing two named items ol.style and ul.style, values are the stylenames to be used to replace the style of ordered and unordered lists created by pandoc. If NULL, no replacement is made.

Default value is list(ol.style = NULL, ul.style = NULL):

ol.style: null
ul.style: null

mapstyles

a named list of style to be replaced in the generated document. list("Normal" = c("Author", "Date")) will result in a document where all paragraphs styled with stylename "Date" and "Author" will be then styled with stylename "Normal".

page_size, page_margins

default page and margins dimensions, these values are used to define the default Word section. See page_size() and page_mar().

reference_num

if TRUE, text for references to sections will be the section number (e.g. '3.2'). If FALSE, text for references to sections will be the text (e.g. 'section title').

...

arguments used by word_document

Value

R Markdown output format to pass to render

Finding stylenames

You can access them in the Word template used. Function styles_info() can let you read these styles.

You need officer to read the stylenames (to get information from a specific "reference_docx", change ref_docx_default in the example below.

library(officer)
docx_file <- system.file(package = "officer", "template", "template.docx")
doc <- read_docx(docx_file)

To read paragraph stylenames:

styles_info(doc, type = "paragraph")

To read table stylenames:

styles_info(doc, type = "table")

To read list stylenames:

styles_info(doc, type = "numbering")

R Markdown yaml

The following demonstrates how to pass arguments in the R Markdown yaml:

---
output:
  officedown::rdocx_document:
    reference_docx: pandoc_template.docx
    tables:
      style: Table
      layout: autofit
      width: 1.0
      caption:
        style: Table Caption
        pre: 'Table '
        sep: ': '
      conditional:
        first_row: true
        first_column: false
        last_row: false
        last_column: false
        no_hband: false
        no_vband: true
    plots:
      style: Normal
      align: center
      caption:
        style: Image Caption
        pre: 'Figure '
        sep: ': '
    lists:
      ol.style: null
      ul.style: null
    mapstyles:
      Normal: ['First Paragraph', 'Author', 'Date']
    page_size:
      width: 8.3
      height: 11.7
      orient: "portrait"
    page_margins:
      bottom: 1
      top: 1
      right: 1.25
      left: 1.25
      header: 0.5
      footer: 0.5
      gutter: 0.5
    reference_num: true
---

Examples

# NOT RUN {
library(rmarkdown)
run_ok <- pandoc_available() &&
  pandoc_version() >= numeric_version("2.0")

if(run_ok){

# minimal example -----
example <- system.file(package = "officedown",
  "examples/minimal_word.Rmd")
rmd_file <- tempfile(fileext = ".Rmd")
file.copy(example, to = rmd_file)

docx_file_1 <- tempfile(fileext = ".docx")
render(rmd_file, output_file = docx_file_1, quiet = TRUE)
render(rmd_file, output_file = docx_file_1, quiet = TRUE,
  intermediates_dir = tempfile())

# bookdown example -----
if(require("bookdown")){

bookdown_loc <- system.file(package = "officedown", "examples/bookdown")

temp_dir <- tempfile()
# uncomment next line to get the result in your working directory
# temp_dir <- "./bd_example"

dir.create(temp_dir, showWarnings = FALSE, recursive = TRUE)
file.copy(
  from = list.files(bookdown_loc, full.names = TRUE),
  to = temp_dir,
  overwrite = TRUE, recursive = TRUE)

render_site(
  input = temp_dir, encoding = 'UTF-8',
  envir = new.env(), quiet = TRUE)

docx_file_2 <- file.path(temp_dir, "_book", "bookdown.docx")

if(file.exists(docx_file_2)){
  message("file ", docx_file_2, " has been written.")
}
}

}
# }