15.5 Child documents
When you feel an R Markdown document is too long, you may consider splitting it into shorter documents, and include them as child documents of the main document via the chunk option
child option takes a character vector of paths to the child documents, e.g.,
Since knitr chunk options can take values from arbitrary R expressions, one application of the
child option is the conditional inclusion of a document. For example, if your report has an appendix containing technical details that your boss may not be interested in, you may use a variable to control whether this appendix is included in the report:
Or if you are writing a news report on a football game that has not taken place yet, you may include different child documents depending on the outcome, e.g.,
child = if (winner == 'brazil') 'brazil.Rmd' else 'germany.Rmd'. Then as soon as the game (between Germany and Brazil) is finished, you can publish your report.
Another way to compile child documents is the function
knitr::knit_child(). You can call this function in an R code chunk or an inline R expression, e.g.,
knit_child() returns a character vector of the knitted output, which we can write back to the main document with
cat() and the chunk option
results = 'asis'.
You can even use a child document as a template, and call
knit_child() on it repeatedly with different parameters. In the example below, we run a regression using
mpg as the response variable and each of the rest of variables in the
mtcars data as the explanatory variable.
To make the above example self-contained, we used the
text argument of
knit_child() instead of a file input to pass the R Markdown content to be knitted. You can certainly write the content to a file, and pass a path to
knit_child() instead. For example, you can save the content below to a file named
And knit the file instead: