data.frame printing

When officedown is loaded in the R Markdown document, data.frames are printed with officedown renderer.

Pandoc does not allow usage of Word table style. Package officedown lets you add Word table styles to data.frame while printed in a R Markdown document.

These table styles must be present in the reference_docx document. It can be read with officer::styles_info(doc, type = "table") or within Word table styles view.

Tables features

The customization of the tables with Word features is possible with the “officedown” package. Word tables can have named styles, a group of settings that can be applied to a table. The settings include formatting for the overall table, rows, columns etc.

there’s no feature to apply a style to individual cells. If this is what you need, use package flextable instead.

The possibilities with officedown are the following:

Global settings

These formatting settings can be defined globally, in the YAML header or per output chunks (in the knitr chunk options).

This corresponds to argument tables in output_format function rdocx_document(). Default value is shown below:

# sample of R markdown yaml header
  style: Table
  layout: autofit
  width: 1.0
    style: Table Caption
    pre: 'Table '
    sep: ': '
    first_row: true
    first_column: false
    last_row: false
    last_column: false
    no_hband: false
    no_vband: true

We have chosen the default values and argument names by trying to get identical or close to the standards bookdown and R Markdown.

YAML header chunk option details
style the Word style name to use for tables.
layout tab.layout ‘autofit’ or ‘fixed’ algorithm. See officer::table_layout.
width tab. width Value of the preferred width of the table in percent (base 1).
    style Word style name to use for table captions.
    pre tab.cap.pre Prefix for numbering chunk (default to “Table”).
    sep tab.cap.sep Suffix for numbering chunk (default to “:”).
    first_row first_row apply or remove formatting from the first row in the table.
    first_column first_column apply or remove formatting from the first column in the table.
    last_row last_row apply or remove formatting from the last row in the table.
    last_column last_column apply or remove formatting from the last column in the table.
    no_hband no_hband don’t display odd and even rows.
    no_vband no_vband don’t display odd and even columns.

Table captions

Table captions (and references) have to be specified in the knitr chunk options (as there should only be distinct values, it does not make sense to provide a default value).

chunk option details
tab.cap Caption label Caption reference unique identifier

How to use these arguments

The minimal set of options to get a table caption is to provide a value to argument tab.cap. This will add a caption before the table, label is the value of tab.cap: {r tab.cap='caption label'}. No reference is provided and the table can not be cross-referenced.

If providing a reference, it will add a caption to the table with a reference:

Overwritting global settings

Global options can be overwritten at any moment with chunk options or with function knitr::opts_chunk$set():

{r tab.cap='caption label','my_ref','another table style'}.

You can change table style for a specific table or caption style.

Column alignment

Column alignment can be modified by using a chunk option named alignment. It expects a character vector of values for each columns. Values can be:

```{r alignment=c("l", "l", "r", "r", "c")} 

How to create Word Table style

To create a table style in your reference_docx corresponding to your needs, edit the document with MS Word and add a new style of type “table” then configure it.

You should see a window that looks like the one below:

In the Define New Table Style window, start give your new style a name. There are a many formatting options available in this window. For example, you can change the font and font style, change the border and cell colors, and change the text alignment. Note there’s no option to apply a style to individual cells, this is a Word limit, Package flextable is to be used if this is what you need.

Once you are happy with the style, save the document - the style is stored within the word document.