Captions and references

Set caption label

Use knitr chunk options fig.cap or tab.cap to specify the label of the caption. If a table, caption will be added before the table, if a graphic, caption will be added after the graphic.

```{r fig.cap="figure caption"}
plot(1:12)
```

```{r tab.cap="table caption"}
head(iris)
```

It will produce an auto-numbered caption associated with a bookmark:

Cross-references

Cross-referencing is particularly interesting when using {bookdown}. Bookdown references and captions are not always satisfying some organizations requirements that impose usage of computed numbered captions and references to them for Word documents. {officedown} bring this feature: caption are autonumbered and a bookmark is set on the chunk containing the number; cross-references are Word references hyperlinked to the captions they are related to.

The functionality will allow the editing of Word documents produced with respect of different references or numbered captions. This is particulary useful when the document is modified in its structure (chapters moved, graphics added manually) or integrated into another Word document.

This is a linked reference to a figure: \@ref(fig:tsplot)

To refer to simple document id, use syntax \@ref(an_id):

Lists of Figures and Tables

You can list and organize the figures or tables in a Word document by creating a table of figures, much like a table of contents.

Using stylename

R Markdown uses the Word paragraph style “Image Caption” for graphic captions. To my knowledge, there is no official feature for table captions and therefore no style associated with table captions. Word, on the other hand, only uses a paragraph style called “Caption” whether the caption is relative to a graph, a table or an equation. Note that this style name is specific to each country.

The choice that has been made with officedown is to let you apply one or different styles for table and graph captions. Default style for graph captions is “Image Caption” and default style for table captions is “Table Caption” (which is also available in R Markdown (and pandoc) Word template.

Create a list of figures with function block_toc or by using officedown chunk <!---BLOCK_TOC{...}--->

If you used two different styles for table and figures captions, use block_toc with argument style set to the caption style name.

block_toc(style = "Table Caption")

OR

<!---BLOCK_TOC{style: "Table Caption"}--->

Using sequence identifier

You might have to (or want to) use only one single style for table and graphic captions and need to generate one table of contents for tables and one for charts.

In that case use block_toc with argument seq_id set by default to tab for table captions and fig for figure captions.

block_toc(seq_id = "tab")

OR

<!---BLOCK_TOC{seq_id: "fig"}--->

What is that sequence id?

When using Word, you can add a list of figures or tables (go to the “References” tab and select “Insert Table of Figures”). By default, you won’t see your sequence in the menu because Word is storing locally 3 sequence names in your profile (for tables, figures and eequation). Although not recommended, you can change tab.lp to Tabelle (or Tableau) and benefit from the feature manually from Word. Again, this is not recommended as it will force you to update that value for little gain.

Sequence options

Legends for tables and figures can be configured as required. We have chosen default values for the options that are classic in terms of usage but these values correspond to the English language. If you are writing in Spanish, German, or another language, you probably want to change these values to match your language.

The values to be configured for the tables are the following:

tables:
  caption:
    style: Table Caption
    pre: 'Table '
    sep: ': '

These values can also be altered via the function knitr::opts_chunk$set().

knitr::opts_chunk$set(
  tab.cap.style = "Table Caption",
  tab.cap.pre = "Table ",
  tab.cap.sep = ": ",
  )

The values to be configured for the figures are the following:

plots:
  caption:
    style: Image Caption
    pre: 'Figure '
    sep: ': '

These values can also be altered via the function knitr::opts_chunk$set().

knitr::opts_chunk$set(
  fig.cap.style = "Image Caption",
  fig.cap.pre = "Figure ",
  fig.cap.sep = ": ",
  )

You can also use at any moment knitr chunk options:

```{r fig.cap="figure caption", fig.cap.style="Image Caption"}
plot(1:12)
```

```{r tab.cap="table caption", tab.cap.style="Table Caption"}
head(iris)
```