The goal of customknitrender is to make it easy to switch between output
formats for rmarkdown files when the files share the output yaml
frontmatter from a single source.
install.packages("customknitrender")Assume that you have a project in RStudio with the following structure:
ProjectRoot
├── article_1.Rmd
├── article_2.Rmd
└── article_3.Rmd
where each article file contains the following output configuration
(header-includes is extra configuration for latex/pdf output):
---
output:
pdf_document:
latex_engine: xelatex
number_sections: yes
html_document: default
word_document: default
header-includes:
- \usepackage{ragged2e}
- \usepackage{indentfirst}
---If you wanted all article rmarkdown files to share the same output
configuration rather than repeating the code within each file and,
optionally, share the same header-includes latex configuration, you
can create an _output.yaml file in the same directory where the
rmarkdown files are, and move the output configurations there, and
also create a header.tex file, and move the header-includes code
there:
ProjectRoot
├── _output.yaml
├── article_1.Rmd
├── article_2.Rmd
├── article_3.Rmd
└── header.tex
where _output.yaml is defined as
pdf_document:
latex_engine: xelatex
number_sections: yes
includes:
in_header: header.tex
html_document: default
word_document: default(notice that no top-bottom dashes are needed nor the output key in the
yaml file), and header.tex as
\usepackage{ragged2e}
\usepackage{indentfirst}(notice that no dashes are needed in the tex file).
With this, the frontmatter of the article files reduces to
---
---
Now all three article files share the same configuration for pdf, html,
and word document output (which is great when you need the same config).
However, when you press the Knit button from RStudio within one of the
article files, regardless of whether you press “Knit to HTML”, “Knit to
PDF”, or “Knit to Word”, the file will be knitted to PDF. This is
because the Knit button runs knitr’s knit function with the first
output type written in _output.yaml. Hence, if you wanted to render
any article file in HTML instead, you would need to move the
html_document key to the top of the _output.yaml file, save the
file, and then go to, say, article_1.Rmd, and knit the file. Hence, for
any time you would like to switch the output format, you would need to
do a cut-paste-save in _output.yaml, and a save in your desired file.
Here is where the customknitrender package comes into play. The
package provides a function, in_format(x), that you can use in the
frontmatter of your rmarkdown files to specify the desired output format
using integers:
---
knit: !r customknitrender::in_format(3)
---
{r}
library(customknitrender)
will render the file in pdf format, where knit is a key to
override the Knit button, and the syntax !r ... is needed to be able
to call a function within yaml content. Using
customknitrender::in_format(33)
renders the file in html format, and using any other integer
defaults to word document format (e.g., in_format(333),
in_format(4), …).
Beware that you can still customize the output format within each individual rmarkdown file if you wish:
---
output:
pdf_document:
toc: true
html_document:
toc: true
knit: !r customknitrender::in_format(3)
---
{r}
library(customknitrender)
will render the file in pdf format using all the keys defined in
_output.yaml for pdf format, while only overwriting the toc key if it
exists.