See about the Tufte Handouts format in R Markdown Definitive Guide
## Installation
You can install the last available released version from
[CRAN](https://cran.r-project.org/package=tufte)
``` r
install.packages('tufte')
```
You can also install the development version of **tufte** from
[GitHub](https://github.com/) with:
``` r
# install.packages("pak")
pak::pak("rstudio/tufte")
```
## Usage
The easiest way to make a new R Markdown document using Tufte style is
from within RStudio. Go to *File \> New File \> R Markdown \> From
template \> Tufte Handout*.
This can also be created from the command line using
``` r
rmarkdown::draft("tufte.Rmd", "tufte_html", "tufte")
```
## Getting help
There are two main places to get help:
1. The [RStudio
community](https://community.rstudio.com/c/r-markdown/10) is a
friendly place to ask any questions about rmarkdown and the R
Markdown family of packages. Use tag **tufte** in your post.
2. [Stack
Overflow](https://stackoverflow.com/questions/tagged/r-markdown+tufte)
is a great source of answers to common rmarkdown questions. It is
also a great place to get help, once you have created a reproducible
example that illustrates your problem.
tufte/man/ 0000755 0001762 0000144 00000000000 14211405254 012152 5 ustar ligges users tufte/man/tufte-package.Rd 0000644 0001762 0000144 00000001742 14404617053 015173 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tufte-package.R
\docType{package}
\name{tufte-package}
\alias{tufte}
\alias{tufte-package}
\title{tufte: Tufte's Styles for R Markdown Documents}
\description{
Provides R Markdown output formats to use Tufte styles for PDF and HTML output.
}
\seealso{
Useful links:
\itemize{
\item \url{https://github.com/rstudio/tufte}
\item Report bugs at \url{https://github.com/rstudio/tufte/issues}
}
}
\author{
\strong{Maintainer}: Christophe Dervieux \email{cderv@posit.co} (\href{https://orcid.org/0000-0003-4474-2498}{ORCID}) [contributor]
Authors:
\itemize{
\item Yihui Xie \email{xie@yihui.name} (\href{https://orcid.org/0000-0003-0645-5666}{ORCID})
\item JJ Allaire
}
Other contributors:
\itemize{
\item Andrzej Oles [contributor]
\item Dave Liepmann (Tufte CSS in inst/rmarkdown/templates/tufte_html/resources) [contributor]
\item Posit Software, PBC [copyright holder, funder]
}
}
\keyword{internal}
tufte/man/tufte_handout.Rd 0000644 0001762 0000144 00000011060 14404616732 015321 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/handout.R, R/html.R, R/utils.R
\name{tufte_handout}
\alias{tufte_handout}
\alias{tufte_book}
\alias{tufte_html}
\alias{newthought}
\alias{margin_note}
\alias{quote_footer}
\alias{sans_serif}
\title{Tufte handout formats (PDF and HTML)}
\usage{
tufte_handout(
fig_width = 4,
fig_height = 2.5,
fig_crop = TRUE,
dev = "pdf",
highlight = "default",
...
)
tufte_book(
fig_width = 4,
fig_height = 2.5,
fig_crop = TRUE,
dev = "pdf",
highlight = "default",
...
)
tufte_html(
...,
tufte_features = c("fonts", "background", "italics"),
tufte_variant = c("default", "envisioned"),
margin_references = TRUE
)
newthought(text)
margin_note(text, icon = "⊕")
quote_footer(text)
sans_serif(text)
}
\arguments{
\item{fig_width}{Default width (in inches) for figures}
\item{fig_height}{Default height (in inches) for figures}
\item{fig_crop}{Whether to crop PDF figures with the command
\command{pdfcrop}. This requires the tools \command{pdfcrop} and
\command{ghostscript} to be installed. By default, \code{fig_crop = TRUE}
if these two tools are available.}
\item{dev}{Graphics device to use for figure output (defaults to pdf)}
\item{highlight}{Syntax highlighting style passed to Pandoc.
Supported built-in styles include "default", "tango", "pygments", "kate",
"monochrome", "espresso", "zenburn", "haddock", and "breezedark".
Two custom styles are also included, "arrow", an accessible color scheme,
and "rstudio", which mimics the default IDE theme. Alternatively, supply a
path to a \samp{.theme} file to use
\href{https://pandoc.org/MANUAL.html#syntax-highlighting}{a custom Pandoc
style}. Note that custom theme requires Pandoc 2.0+.
Pass \code{NULL} to prevent syntax highlighting.}
\item{...}{Other arguments to be passed to \code{\link[=pdf_document]{pdf_document()}} or
\code{\link[=html_document]{html_document()}} (note you cannot use the \code{template}
argument in \code{tufte_handout} or the \code{theme} argument in
\code{tufte_html()}; these arguments have been set internally)}
\item{tufte_features}{A character vector of style features to enable:
\code{fonts} stands for the \code{et-book} fonts in the \code{tufte-css}
project, \code{background} means the lightyellow background color of the
page, and \code{italics} means whether to use italics for the headers. You
can enable a subset of these features, or just disable all of them by
\code{NULL}. When this argument is not used and the \code{tufte_variant}
argument is not \code{default}, no features are enabled.}
\item{tufte_variant}{A variant of the Tufte style. Currently supported styles
are \code{default} (from the \code{tufte-css} project), and
\code{envisioned} (inspired by the project \verb{Envisioned CSS}
\url{https://github.com/nogginfuel/envisioned-css} but essentially just
sets the font family to \verb{Roboto Condensed}, and changed the
background/foreground colors).}
\item{margin_references}{Whether to place citations in margin notes.}
\item{text}{A character string to be presented as a \dQuote{new thought}
(using small caps), or a margin note, or a footer of a quote}
\item{icon}{A character string to indicate there is a hidden margin note when
the page width is too narrow (by default it is a circled plus sign)}
}
\description{
Templates for creating handouts according to the style of Edward R. Tufte and
Richard Feynman.
}
\details{
\code{tufte_handout()} provides the PDF format based on the Tufte-LaTeX
class: \url{https://tufte-latex.github.io/tufte-latex/}.
\code{tufte_html()} provides the HTML format based on the Tufte CSS:
\url{https://edwardtufte.github.io/tufte-css/}.
\code{newthought()} can be used in inline R expressions in R
Markdown
\if{html}{\out{See (Xie 2020a)Xie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in R..
" [2] "See Xie (2020b)Xie, Yihui. 2020b. Knitr: A General-Purpose Package for Dynamic Report Generation in R - Duplicate.
" [3] "See Xie (2020a)Xie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in R. and Xie, Allaire, and Grolemund (2018Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC.)
" [4] "See (Xie 2020a)Xie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in R. and (Xie, Allaire, and Grolemund 2018Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC.)
" --- Code margin_references(x) Output [1] "See (Xie 2020a).
" [2] "See Xie (2020b)
" [3] "See Xie (2020a) and Xie, Allaire, and Grolemund (2018)
" [4] "See (Xie 2020a) and (Xie, Allaire, and Grolemund 2018)
" [5] "Xie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in R.
" [8] "———. 2020b. Knitr: A General-Purpose Package for Dynamic Report Generation in R - Duplicate.
" [11] "Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC.
" [14] "See (Xie 2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.).
" [2] "See Xie (2020bXie, Yihui. 2020b. Knitr: A General-Purpose Package for Dynamic Report Generation in r - Duplicate. https://yihui.org/knitr/.)
" [3] "See Xie (2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.) and Xie, Allaire, and Grolemund (2018Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.)
" [4] "See (Xie 2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.) and (Xie, Allaire, and Grolemund 2018Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.)
" --- Code margin_references(x) Output [1] "See (Xie 2020a).
" [2] "See Xie (2020b)
" [3] "See Xie (2020a) and Xie, Allaire, and Grolemund (2018)
" [4] "See (Xie 2020a) and (Xie, Allaire, and Grolemund 2018)
" [5] "See (Xie, 2020aXie, Y. (2020a). Knitr: A general-purpose package for dynamic report generation in r. Retrieved from https://yihui.org/knitr/).
" [2] "See Xie (2020bXie, Y. (2020b). Knitr: A general-purpose package for dynamic report generation in r - duplicate. Retrieved from https://yihui.org/knitr/)
" [3] "See Xie (2020aXie, Y. (2020a). Knitr: A general-purpose package for dynamic report generation in r. Retrieved from https://yihui.org/knitr/) and Xie, Allaire, & Grolemund (2018Xie, Y., Allaire, J. J., & Grolemund, G. (2018). R markdown: The definitive guide. Boca Raton, Florida: Chapman; Hall/CRC. Retrieved from https://bookdown.org/yihui/rmarkdown)
" [4] "See (Xie, 2020aXie, Y. (2020a). Knitr: A general-purpose package for dynamic report generation in r. Retrieved from https://yihui.org/knitr/) and (Xie et al., 2018Xie, Y., Allaire, J. J., & Grolemund, G. (2018). R markdown: The definitive guide. Boca Raton, Florida: Chapman; Hall/CRC. Retrieved from https://bookdown.org/yihui/rmarkdown)
" --- Code margin_references(x) Output [1] "See (Xie 2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.).
" [2] "See Xie (2020bXie, Yihui. 2020b. Knitr: A General-Purpose Package for Dynamic Report Generation in r - Duplicate. https://yihui.org/knitr/.)
" [3] "See Xie (2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.) and Xie, Allaire, and Grolemund (2018Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.)
" [4] "See (Xie 2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.) and (Xie, Allaire, and Grolemund 2018Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.)
" tufte/tests/testthat/_snaps/html.md 0000644 0001762 0000144 00000000642 14445043572 017166 0 ustar ligges users # add marginnote Code marginnote_html("text") Output [1] "text" --- Code marginnote_html("text", "#") Output [1] "text" tufte/tests/testthat/_snaps/new-citeproc-post-2.14.0.2/ 0000755 0001762 0000144 00000000000 14174473530 022140 5 ustar ligges users tufte/tests/testthat/_snaps/new-citeproc-post-2.14.0.2/html.md 0000644 0001762 0000144 00000034130 14174473530 023427 0 ustar ligges users # put references in margin when link-citations: yes Code margin_references(x) Output [1] "See (Xie 2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.).
" [2] "See Xie (2020b)Xie, Yihui. 2020b. Knitr: A General-Purpose Package for Dynamic Report Generation in r - Duplicate. https://yihui.org/knitr/.
" [3] "See Xie (2020a)Xie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/. and Xie, Allaire, and Grolemund (2018)Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.
" [4] "See (Xie 2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.) and (Xie, Allaire, and Grolemund 2018Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.)
" --- Code margin_references(x) Output [1] "See (Xie 2020a).
" [2] "See Xie (2020b)
" [3] "See Xie (2020a) and Xie, Allaire, and Grolemund (2018)
" [4] "See (Xie 2020a) and (Xie, Allaire, and Grolemund 2018)
" [5] "See (Xie, 2020aXie, Y. (2020a). Knitr: A general-purpose package for dynamic report generation in r. Retrieved from https://yihui.org/knitr/).
" [2] "See Xie (2020b)Xie, Y. (2020b). Knitr: A general-purpose package for dynamic report generation in r - duplicate. Retrieved from https://yihui.org/knitr/
" [3] "See Xie (2020a)Xie, Y. (2020a). Knitr: A general-purpose package for dynamic report generation in r. Retrieved from https://yihui.org/knitr/ and Xie, Allaire, & Grolemund (2018)Xie, Y., Allaire, J. J., & Grolemund, G. (2018). R markdown: The definitive guide. Boca Raton, Florida: Chapman; Hall/CRC. Retrieved from https://bookdown.org/yihui/rmarkdown
" [4] "See (Xie, 2020aXie, Y. (2020a). Knitr: A general-purpose package for dynamic report generation in r. Retrieved from https://yihui.org/knitr/) and (Xie, Allaire, & Grolemund, 2018Xie, Y., Allaire, J. J., & Grolemund, G. (2018). R markdown: The definitive guide. Boca Raton, Florida: Chapman; Hall/CRC. Retrieved from https://bookdown.org/yihui/rmarkdown)
" --- Code margin_references(x) Output [1] "See (Xie 2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.).
" [2] "See Xie (2020b)Xie, Yihui. 2020b. Knitr: A General-Purpose Package for Dynamic Report Generation in r - Duplicate. https://yihui.org/knitr/.
" [3] "See Xie (2020a)Xie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/. and Xie, Allaire, and Grolemund (2018)Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.
" [4] "See (Xie 2020aXie, Yihui. 2020a. Knitr: A General-Purpose Package for Dynamic Report Generation in r. https://yihui.org/knitr/.) and (Xie, Allaire, and Grolemund 2018Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.)
" tufte/tests/testthat/test-html.R 0000644 0001762 0000144 00000004160 14211403147 016445 0 ustar ligges users test_that("add marginnote", { expect_snapshot(marginnote_html("text")) expect_snapshot(marginnote_html("text", "#")) }) expect_refs_margin <- function(moved = FALSE, options = NULL, ..., variant = NULL) { rmd <- test_path("resources/margins_references.Rmd") out <- withr::local_tempfile(fileext = ".html") rmd_temp <- withr::local_tempfile(fileext = ".Rmd") xfun::write_utf8( knitr::knit_expand(rmd, linked = if (moved) "yes" else "no"), rmd_temp ) rmarkdown::pandoc_convert(basename(rmd_temp), "html4", "markdown", output = out, citeproc = TRUE, verbose = FALSE, wd = dirname(rmd_temp), options = c("--wrap", "preserve", options), ... ) x <- xfun::read_utf8(out) expect_snapshot(margin_references(x), variant = variant) } citeproc_variant <- function() { if (!rmarkdown::pandoc_available("2.11")) { "pandoc-citeproc" } else if (!rmarkdown::pandoc_available("2.14.1")) { # new citeproc creates links on author "new-citeproc-post-2.14.0.2" } else { # Pandoc 2.14.1 fixed that "new-citeproc-post-2.14.1" } } pandoc_variant <- citeproc_variant() test_that("put references in margin when link-citations: yes", { skip_on_cran() skip_if_not_pandoc() expect_refs_margin(moved = TRUE, variant = pandoc_variant) expect_refs_margin(moved = FALSE, variant = pandoc_variant) }) test_that("put references in margin when link-citations: yes using csl", { skip_on_cran() # requires recent Pandoc skip_if_not_pandoc("2.11") skip_if_offline("zotero.org") expect_refs_margin(moved = TRUE, variant = pandoc_variant, c("--csl", "https://www.zotero.org/styles/apa-6th-edition")) expect_refs_margin(moved = TRUE, variant = pandoc_variant, c("--csl", "https://www.zotero.org/styles/chicago-author-date-16th-edition")) }) test_that("footnotes are correctly parsed", { skip_on_cran() skip_if_not_pandoc() pandoc_html <- local_pandoc_convert("Here is some text^[This should be a sidenote].", to = "html4" ) expect_identical( parse_footnotes(pandoc_html), list(items = "This should be a sidenote", range = 2:7) ) }) tufte/tests/testthat.R 0000644 0001762 0000144 00000000072 14174473530 014535 0 ustar ligges users library(testthat) library(tufte) test_check("tufte") tufte/R/ 0000755 0001762 0000144 00000000000 14404616351 011606 5 ustar ligges users tufte/R/utils.R 0000644 0001762 0000144 00000006235 14404616351 013077 0 ustar ligges users .onLoad <- function(lib, pkg) { # this engine will be overridden in tufte_html/tufte_handout formats knitr::knit_engines$set(marginfigure = function(options) { 'Placeholder (you should not see this)' }) } #' @details `newthought()` can be used in inline R expressions in R #' Markdown #' ```r #' `r newthought(Some text)` #' ``` #' and it works for both #' HTML (\samp{text}) and PDF #' (\samp{\\newthought{text}}) output. #' @param text A character string to be presented as a \dQuote{new thought} #' (using small caps), or a margin note, or a footer of a quote #' @rdname tufte_handout #' @export #' @examples newthought("In this section") newthought <- function(text) { if (is_html_output()) { sprintf('%s', text) } else if (is_latex_output()) { sprintf("\\newthought{%s}", text) } else { sprintf('%s', text) } } #' @details `margin_note()` can be used in inline R expressions to write a #' margin note (like a sidenote but not numbered). #' @param icon A character string to indicate there is a hidden margin note when #' the page width is too narrow (by default it is a circled plus sign) #' @rdname tufte_handout #' @importFrom knitr is_html_output is_latex_output #' @export margin_note <- function(text, icon = "⊕") { if (is_html_output()) { marginnote_html(sprintf('%s', text), icon) } else if (is_latex_output()) { sprintf("\\marginnote{%s}", text) } else { warning("marginnote() only works for HTML and LaTeX output", call. = FALSE) text } } #' @details `quote_footer()` formats text as the footer of a quote. It puts #' `text` in \samp{} for HTML output, and #' after \samp{\\hfill} for LaTeX output (to right-align text). #' @rdname tufte_handout #' @export quote_footer <- function(text) { if (is_html_output()) { sprintf("", text) } else if (is_latex_output()) { sprintf("\\hfill %s", text) } else { warning("quote_footer() only works for HTML and LaTeX output", call. = FALSE) text } } #' @details `sans_serif()` applies sans-serif fonts to `text`. #' @rdname tufte_handout #' @export sans_serif <- function(text) { if (is_html_output()) { sprintf('%s', text) } else if (is_latex_output()) { sprintf("\\textsf{%s}", text) } else { warning("sans_serif() only works for HTML and LaTeX output", call. = FALSE) text } } template_resources <- function(name, ...) { system.file("rmarkdown", "templates", name, "resources", ..., package = "tufte") } gsub_fixed <- function(...) gsub(..., fixed = TRUE) pandoc2.0 <- function() rmarkdown::pandoc_available("2.0") # add --wrap=preserve to pandoc args for pandoc 2.0: # https://github.com/rstudio/bookdown/issues/504 # https://github.com/rstudio/tufte/issues/115 add_wrap_preserve <- function(args, pandoc2 = pandoc2.0) { if (pandoc2 && !length(grep("--wrap", args))) { c("--wrap", "preserve", args) } else { args } } tufte/R/tufte-package.R 0000644 0001762 0000144 00000000143 14211405250 014435 0 ustar ligges users #' @keywords internal "_PACKAGE" ## usethis namespace: start ## usethis namespace: end NULL tufte/R/handout.R 0000644 0001762 0000144 00000006335 14211403140 013364 0 ustar ligges users #' Tufte handout formats (PDF and HTML) #' #' Templates for creating handouts according to the style of Edward R. Tufte and #' Richard Feynman. #' #' `tufte_handout()` provides the PDF format based on the Tufte-LaTeX #' class:'] <- '
' # move to the same line as