3 Tips

3.1 Overview

3.2 General set-up

Be as modular and simple as you can.
Don’t make everyone in your team be the markdown wizard. You only need one person to build the framework.
Use simple child Rmds so that other team members work only on simple Rmd/qmd flat files.
Don’t put all your tables or figures in one huge file: Table xyz.Rmd/qmd, Table abc.Rmd/qmd. Have your dedicated markdown wizard figure out the automatic numbering.
Copy reports built by others who are doing something similar to you. TALK within your center or across centers and share work.

3.3 Tips

3.3.1 Cross-references

This can be really troublesome unless you use an output that already has cross-references as part of the design. For R Markdown,

{bookdown} outputs for html and PDF
{officedown} for Word

These output formats give you access to cross-referencing via the \@ref(xxx:yyy) format and if you use bookdown::pdf_book, this will also work with PDF.

However, Quarto makes cross-references, auto-numbering and cross-referencing of tables and figures super easy. Quarto cross-ref page.

For example, we can make a figure with the chunk label fig-plot like so.

```{r}
#| label: fig-plot
#| fig-cap: "Plot"

plot(cars)
```

The later in the text we use @fig-plot to get Figure 3.2.

3.3.2 Chunk labels

When using R Markdown (or Quarto), it is best not to use chunk labels in the your Rmd/qmd children. It’s too easy to get duplicate labels accidentally.

3.3.3 File paths

if you need to reference a file in a folder, let R create the path so that it is compatible across systems:

file.path('figures', 'figure1.Rmd')

I typically use the {here} package so that my code doesn’t break if I happen to issue a change workspace directory command.

here::here('images', 'logo.png')

3.3.4 Tables in for loops

Making tables within for loops is tricky and it is different if you are outputting to Word versus html and also depends on what package that you use. See my Rmd/qmd files in the tables folder for examples of how to set it up, but also be prepared for things breaking in the future as package writers change things. This feature is really fluid. Web searches on stackoverflow are key for solving these problems.

3.4 Working with Word

For many of us, Word is part of our team’s workflow. Here are some tips if that is the case for you:

Check out the officeverse: officedown and flextable R packages.
Quarto has greatly improved Word integration so many of the problems we faced with Word output may soon be solved.
Don’t build the whole report in one file. Work on individual text sections and then have RStudio (via pandoc/knitr) assemble the report (text, figures, tables) from the individual parts.
How to deal with the team needing to review the assembled document (text, figures, tables):
- Try to modularize. So maybe make individual chapters and have review happen at that level. Then you incorporate the changes into the plain text manually.
- Use templates to make your Word doc look the way you want. The default Word template is bare bones. See my example and read about using Word templates with Quartro here and R Markdown here .

3.4.1 Making tables look nice in Word

The example in Table_Counts.Rmd and Table_Counts_flex.Rmd shows you tricks to make nice Word tables.

how to include a page break in your Word doc between tables.
using format="pandoc" for the table
using results='asis' and print() so you can use for loops.
centering your tables is next to impossible with kable(). Use the {flextable} package if you need that.

3.4.2 New pages

This is how to get a new page in Word. Make sure you are in print view on the word doc, otherwise you won’t see any of the pages.

```{=openxml}
<w:p><w:r><w:br w:type="page"/></w:r></w:p>
```

3.5 Output templates with Quarto

Quarto is working on templates to make output to different formats easy. Here is an example of journal templates quarto-journals.

3.6 Weird Quarto quirks

If you use

---
title: MyTitle
---

as your title spec, then you won’t get the first header 2 in your pdf. Use # instead.

If you have 2 # levels in a qmd file, you only the first chapter appearing in the TOC. The others appear weirdly as sub-chapters.
with flextable, your table captions from knitr yaml disappear if the table breaks across a page.

# Tips ## Overview ```{r} #| label: "fig-chinook" #| fig-cap: "chapter 1 plot" plot(pressure) ``` ## General set-up * Be as modular and simple as you can. * Don't make everyone in your team be the markdown wizard. You only need one person to build the framework. * Use simple child Rmds so that other team members work only on simple Rmd/qmd flat files. * Don't put all your tables or figures in one huge file: `Table xyz.Rmd/qmd`, `Table abc.Rmd/qmd`. Have your dedicated markdown wizard figure out the automatic numbering. * Copy reports built by others who are doing something similar to you. TALK within your center or across centers and share work. ## Tips ### Cross-references This can be really troublesome unless you use an output that already has cross-references as part of the design. For R Markdown, * {bookdown} outputs for html and PDF * {officedown} for Word These output formats give you access to cross-referencing via the `\@ref(xxx:yyy)` format and if you use `bookdown::pdf_book`, this will also work with PDF. However, Quarto makes cross-references, auto-numbering and cross-referencing of tables and figures super easy. [Quarto cross-ref page](https://quarto.org/docs/authoring/cross-references.html). For example, we can make a figure with the chunk label `fig-plot` like so. ````{verbatim} ```{r} #| label: fig-plot #| fig-cap: "Plot" plot(cars) ``` ```` The later in the text we use `@fig-plot` to get @fig-plot. ```{r echo=FALSE} #| label: fig-plot #| fig-cap: "This is a plot of some data" plot(cars) ``` ### Chunk labels * When using R Markdown (or Quarto), it is best not to use chunk labels in the your Rmd/qmd children. It's too easy to get duplicate labels accidentally. ### File paths * if you need to reference a file in a folder, let R create the path so that it is compatible across systems: ``` file.path('figures', 'figure1.Rmd') ``` * I typically use the {here} package so that my code doesn't break if I happen to issue a change workspace directory command. ``` here::here('images', 'logo.png') ``` ### Tables in for loops Making tables within `for` loops is tricky and it is different if you are outputting to Word versus html and also depends on what package that you use. See my Rmd/qmd files in the tables folder for examples of how to set it up, but also be prepared for things breaking in the future as package writers change things. This feature is really fluid. Web searches on stackoverflow are key for solving these problems. ## Working with Word For many of us, Word is part of our team's workflow. Here are some tips if that is the case for you: * Check out the [officeverse](https://ardata-fr.github.io/officeverse/index.html): [officedown](https://CRAN.R-project.org/package=officedown) and [flextable](https://CRAN.R-project.org/package=flextable) R packages. * Quarto has greatly [improved Word](https://quarto.org/docs/output-formats/ms-word.html) integration so many of the problems we faced with Word output may soon be solved. * Don't build the whole report in one file. Work on individual text sections and then have RStudio (via pandoc/knitr) assemble the report (text, figures, tables) from the individual parts. * How to deal with the team needing to review the assembled document (text, figures, tables): * Try to modularize. So maybe make individual chapters and have review happen at that level. Then you incorporate the changes into the plain text manually. * Use templates to make your Word doc look the way you want. The default Word template is bare bones. See my example and read about using Word templates with Quartro [here](https://quarto.org/docs/output-formats/ms-word-templates.html) and R Markdown [here](https://bookdown.org/yihui/rmarkdown-cookbook/word-template.html) . ### Making tables look nice in Word The example in `Table_Counts.Rmd` and `Table_Counts_flex.Rmd` shows you tricks to make nice Word tables. * how to include a page break in your Word doc between tables. * using `format="pandoc"` for the table * using `results='asis'` and `print()` so you can use `for` loops. * centering your tables is next to impossible with `kable()`. Use the {[flextable](https://ardata-fr.github.io/flextable-book/)} package if you need that. ### New pages This is how to get a new page in Word. Make sure you are in print view on the word doc, otherwise you won't see any of the pages. ```{r echo=FALSE, comment=""} cat('```{=openxml}\n<w:p><w:r><w:br w:type="page"/></w:r></w:p>\n```') ``` ## Output templates with Quarto Quarto is working on templates to make output to different formats easy. Here is an example of journal templates [quarto-journals](https://github.com/quarto-journals/). ## Weird Quarto quirks * If you use ``` --- title: MyTitle --- ``` as your title spec, then you won't get the first header 2 in your pdf. Use `# ` instead. * If you have 2 `# ` levels in a qmd file, you only the first chapter appearing in the TOC. The others appear weirdly as sub-chapters. * with flextable, your table captions from knitr yaml disappear if the table breaks across a page. ```{=openxml} <w:p><w:r><w:br w:type="page"/></w:r></w:p> ```