Yihui Xie, Karl Broman, and Ian Lyttle
2016/06/27 @ Stanford, useR! 2016
@xieyihui @rstudio#useR2016)@kwbroman@ijlyttle
i.e. computing languages + authoring languages
We built a linear regression model.
```{r}
fit <- lm(dist ~ speed, data = cars)
b <- coef(fit)
plot(fit)
``
The slope of the regression is `r b[1]`.# headers, > blockquotes**bold**, _italic_- lists[text](url)$\sum_{i=1}^n \alpha_i$ = \(\sum_{i=1}^n \alpha_i\)```r)raw HTML/LaTeX (limitation: raw HTML only works for HTML output, and raw LaTeX only for LaTeX/PDF output)
<div class="my-class">
</div>
_emphasis_ and \emph{emphasis}^[A footnote here.][@joe2014]without rmarkdown, you have to call knitr and Pandoc separately, e.g.
# in R
library(knitr)
knit('input.Rmd') # -> input.md# in command line
pandoc -t beamer -o output.pdf --smart input.mdyou can specify a lot of Pandoc and knitr options using the R syntax, e.g. Pandoc argument --toc corresponds to toc = TRUE in rmarkdown (similarly, fig_width = 5 in rmarkdown corresponds to opts_chunk$set(fig.width = 5) in knitr)
command-line usage
library(rmarkdown)
render('input.Rmd')
render('input.Rmd', pdf_document())
render('input.Rmd', word_document())
render('input.Rmd', beamer_presentation())
render('input.Rmd', ioslides_presentation())use the RStudio IDE (click the Knit button)
YAML metadata in R Markdown documents (recommended)
---
output:
html_document:
toc: true
number_sections: true
fig_height: 6
---pass to rmarkdown output format functions
rmarkdown::render(
'input.Rmd', html_document(
toc = TRUE,
number_sections = TRUE,
fig_height = 6
)
)you can pass a CSS file to the css argument of the output format, e.g.
---
output:
html_document:
css: my_style.css
---a simple example of my_style.css (change the font size of the second level headers to be 30px)
h2 {
font-size: 30px;
}includes option to add more stuff to the LaTeX outputtypically you want to use the sub-option in_header to customize the LaTeX preamble, e.g.
---
output:
pdf_document:
includes:
in_header: my_preamble.tex
---my_preamble.tex may load more LaTeX packages, set options, and so on, e.g.
\usepackage{booktabs}
\usepackage{ctexcap}If none of the existing options can give you the output you desire, you can simply replace the Pandoc template, which allows you to customize everything.
When Pandoc converts Markdown to another output format, it uses a template under the hood (specified via the --template option of Pandoc, or template argument of most output format functions in rmarkdown).
The template is a plain text file that contains some variables of the form $variable$. These variables will be replaced by their values generated by Pandoc.
A minimal HTML template:
<html>
<head>
<title>$title$</title>
</head>
<body>
$body$
</body>
</html>Variables are typically read from the YAML metadata of the Markdown document, such as $title$, e.g.
---
title: A _Nice_ Markdown Document
---The value of a variable can be different for different output formats, e.g. $title$ is A \emph{Nice} Markdown Document when the output format is LaTeX, and A <em>Nice</em> Markdown Document for HTML output.
install.packages('rticles')output: word_document);save the document, and use it as the template for future R Markdown document;
---
output:
word_document:
reference_docx: my_template.docx
---html_vignette() and the tufte package (tufte::tufte_html(), and tufte::tufte_handout())Take html_document() for example:
str(rmarkdown::html_document(), 2)List of 10
$ knitr :List of 5
..$ opts_knit : NULL
..$ opts_chunk :List of 5
..$ knit_hooks : NULL
..$ opts_hooks : NULL
..$ opts_template: NULL
$ pandoc :List of 6
..$ to : chr "html"
..$ from : chr "markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash"
..$ args : chr [1:8] "--smart" "--email-obfuscation" "none" "--self-contained" ...
..$ keep_tex : logi FALSE
..$ latex_engine: chr "pdflatex"
..$ ext : NULL
$ keep_md : logi FALSE
$ clean_supporting : logi TRUE
$ pre_knit :function (...)
$ post_knit :function (...)
$ pre_processor :function (...)
$ intermediates_generator:function (original_input, encoding, intermediates_dir)
$ post_processor :function (metadata, input_file, output_file, clean, verbose)
$ on_exit :function ()
- attr(*, "class")= chr "rmarkdown_output_format"It is a list of knitr and Pandoc options, plus some functions (pre/post processors). This list is typically generated by rmarkdown::output_format(). Type rmarkdown::html_document or rmarkdown::pdf_document in the R console, and take a look at the last few lines of the source code.
rmarkdown::html_vignette: the key idea is to get rid of the large Bootstrap dependency (theme = NULL) to reduce the R package size, then apply a lightweight CSS theme (vignette.css in rmarkdown) to the HTML outputrmarkdown::rtf_document: specify the output format to be rtf (pandoc_options(to = 'rtf'))rtf to epub or epub3, and you may also add more options specific to EPUB (such as the cover image)tufte::tufte_html, tufte::tufte_handoutrmarkdown::output_format() to specify the output format, they are based on existing formats html_document() and pdf_document(), and modify the lists afterwardstufte_handout modified the plot chunk hook of knitr to support new chunk options fig.margin = TRUE and fig.fullwidth = TRUEtufte_html applied a new CSS file (tufte.css) to the HTML output, and heavily hacked the HTML output using a post-processor to place captions, footnotes and references in the margindemo http://rstudio.github.io/tufte
if (!require('tufte')) install.packages('tufte')
file.edit(
system.file(
'rmarkdown', 'templates', 'tufte_html', 'skeleton', 'skeleton.Rmd',
package = 'tufte'
)
)devtools::install_github('rstudio/bookdown'))gitbook/html_bookpdf_bookepub_bookgrep(), gsub(), gregexpr(), regmatches(), …)rmarkdown::render_siteindex.(R)md and _site.ymlBuild button to build the websiteinst/htmlwidgets directory (JS/CSS dependencies) in a package
htmlwidgets::createWidget()
htmltools::htmlDependency()HTMLWidgets.widget({
name: "FOO",
type: "output",
initialize: function(el, width, height) {
// initialize the element
},
renderValue: function(el, data, instance) {
// render the data in el, e.g.
// $(el).DataTable(data.options);
}
})instead of ```{r}, use ```{lang}, where lang is the language name (e.g. ```{Rcpp}); currently supported languages are
sort(names(knitr::knit_engines$get()))## [1] "asis" "asy" "awk"
## [4] "bash" "block" "c"
## [7] "cat" "coffee" "css"
## [10] "dot" "fortran" "gawk"
## [13] "groovy" "haskell" "highlight"
## [16] "js" "lein" "mysql"
## [19] "node" "perl" "psql"
## [22] "python" "Rcpp" "Rscript"
## [25] "ruby" "sas" "scala"
## [28] "sed" "sh" "stan"
## [31] "stata" "tikz" "zsh"they are not as well supported as R; typically these code chunks are executed simply via system(), e.g. a Python code chunk print(1) is executed as system("python -c 'print(1)'") in R, and the text output (as side effects) is collected