Skip to contents

Tufte handout formats (PDF and HTML)

Source: R/handout.R, R/html.R, R/utils.R
tufte_handout.Rd

Templates for creating handouts according to the style of Edward R. Tufte and Richard Feynman.

Usage

tufte_handout(
  fig_width = 4,
  fig_height = 2.5,
  fig_crop = "auto",
  dev = "pdf",
  highlight = "default",
  margin_fig_pos = NULL,
  ...
)

tufte_book(
  fig_width = 4,
  fig_height = 2.5,
  fig_crop = "auto",
  dev = "pdf",
  highlight = "default",
  margin_fig_pos = NULL,
  ...
)

tufte_handout2(...)

tufte_book2(...)

tufte_html2(...)

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

fig_width

Default width (in inches) for figures

fig_height

Default height (in inches) for figures

fig_crop

Whether to crop PDF figures with the command pdfcrop. This requires the tools pdfcrop and ghostscript to be installed. By default, fig_crop = TRUE if these two tools are available.

dev

Graphics device to use for figure output (defaults to pdf)

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 .theme file to use a custom Pandoc style. Note that custom theme requires Pandoc 2.0+.

Pass NULL to prevent syntax highlighting.

margin_fig_pos

Default vertical offset for margin figures (a LaTeX length such as "0cm" or "-5pt"). When set, this value is used as the fig.pos for all chunks with fig.margin = TRUE, unless the chunk specifies its own fig.pos. This avoids the problem of setting fig.pos globally via knitr::opts_chunk$set(), which would also affect regular figures where fig.pos is a placement specifier (e.g. "htbp"), not a length. Can also be set per-chunk or via knitr::opts_chunk$set() as the margin_fig_pos chunk option. Defaults to NULL (use the Tufte-LaTeX class default of -1.2ex).

...

Other arguments to be passed to rmarkdown::pdf_document() or rmarkdown::html_document() (note you cannot use the template argument in tufte_handout or the theme argument in tufte_html(); these arguments have been set internally)

tufte_features

A character vector of style features to enable: fonts stands for the et-book fonts in the tufte-css project, background means the lightyellow background color of the page, and italics means whether to use italics for the headers. You can enable a subset of these features, or just disable all of them by NULL. When this argument is not used and the tufte_variant argument is not default, no features are enabled.

tufte_variant

A variant of the Tufte style. Currently supported styles are default (from the tufte-css project), and envisioned (inspired by the project Envisioned CSS https://github.com/nogginfuel/envisioned-css but essentially just sets the font family to Roboto Condensed, and changed the background/foreground colors).

margin_references

Whether to place citations in margin notes.

text

A character string to be presented as a “new thought” (using small caps), or a margin note, or a footer of a quote

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)

Value

tufte_handout(), tufte_book(), tufte_html(), and the bookdown wrappers tufte_handout2(), tufte_book2(), and tufte_html2() return an R Markdown output format object that can be passed to rmarkdown::render(). The inline helpers newthought(), margin_note(), quote_footer(), and sans_serif() return a character string with HTML or LaTeX markup depending on the active output format.

Details

tufte_handout() provides the PDF format based on the Tufte-LaTeX class: https://tufte-latex.github.io/tufte-latex/.

tufte_handout2() and tufte_book2() are wrappers around bookdown::pdf_book() that use the corresponding tufte format as the base format. They support bookdown text references ((ref:label)) in figure and table captions, cross-references, and other bookdown extensions. Requires the bookdown package to be installed.

tufte_html() provides the HTML format based on the Tufte CSS: https://edwardtufte.github.io/tufte-css/.

tufte_html2() is a wrapper around bookdown::html_document2() that uses tufte_html() as the base format, enabling text references and cross-references. Requires the bookdown package.

newthought() can be used in inline R expressions in R Markdown

`r newthought(Some text)`

and it works for both HTML (<span class="newthought">text</span>) and PDF (\newthought{text}) output.

margin_note() can be used in inline R expressions to write a margin note (like a sidenote but not numbered).

quote_footer() formats text as the footer of a quote. It works in any HTML or LaTeX output format, not only tufte formats, and tries to render text consistently across formats:

  • If text starts with "---" (or an em-dash), an em-dash + non-breaking space is rendered before the rest of the text in every output. The leading "---" is stripped from text to avoid duplication when the destination format would otherwise inject its own em-dash.

  • For tufte HTML, text is wrapped in a <footer> element styled by tufte.css. For non-tufte HTML (e.g. rmarkdown::html_document(), including bslib Bootstrap 4 and 5 themes), text is wrapped in a <footer class="blockquote-footer"> so that Bootstrap's .blockquote-footer styling (including the ::before em-dash) applies. An inline text-align: right is added in both cases.

  • For LaTeX output (tufte or non-tufte), text is prepended with \hfill to right-align it. Pandoc's smart-punctuation extension converts a leading "---" to an em-dash glyph.

quote_footer() detects whether the active output is a tufte format via the tufte.format entry that the tufte output formats register in knitr::opts_knit.

sans_serif() applies sans-serif fonts to text.

References

See https://rstudio.github.io/tufte/ for an example.

Examples

library(tufte)
newthought("In this section")
#> [1] "<span style=\"font-variant:small-caps;\">In this section</span>"