Reports with Quarto and R Markdown

The idea is to write one document for people and let the machine extract and run the program that is inside it. The document has the explanation, the code and, after it is processed, the results, so the explanation cannot drift away from the numbers it describes. Two operations are named after the original tools: to weave is to run the code and produce the readable document, and to tangle is to extract the code and produce the program. In R, Sweave was the first implementation and it is still part of R; knitr, which grew out of the same idea with more output formats and more options, is the engine of both current systems, and its function names remember the words: knit() weaves, purl() tangles, after the knitting term "knit one, purl one" in the help page of knit().

A document in either system is a Markdown file with three kinds of content. The YAML header, between two lines of three hyphens at the top of the file, holds metadata and options: the title, the output format, the parameters, the execution options. Markdown is the prose. Code chunks, fenced with three backticks and the language in braces, are code that is run when the document is rendered, and inline code is a short expression inside a sentence. Rendering has two steps, shown in the table with the programs that do each of them.

Source: Quarto documentation: Using R

The consequence of this arrangement is that the R side of a document does not change when the program around it changes. A Quarto document with R chunks is executed by knitr, exactly like an R Markdown document; the Quarto documentation says so, and says that Quarto can render most existing .Rmd files without modification. What differs is the packaging: how options are written, the names of the output formats, and what is available on top (projects, cross-references, a larger set of formats). The next sections use the shelf report to show each piece in the order in which a reader meets it.

The report answers two questions about the loans: how many loans were made in each month since a given month, and which members have loans that were overdue. A loan is overdue when it was out for more than loan_days days; a loan that has not been returned counts up to shelf_today. The project directory has the two data files and the document:

Source: Quarto documentation: Project Basics

The document, report.qmd, is the following. Its header gives the title, asks for the html format, declares one parameter, since, with the default 2026-01, and sets echo: false for the whole document with the execute key, so that the code is not shown unless a chunk asks for it. The first chunk, with include: false, reads the data and computes the loans of interest: it runs, and nothing of it is shown. The paragraph after it contains four pieces of inline code. The table and the figure chunks have labels that start with tbl- and fig-, which is how Quarto makes them cross-referenceable, so the text can say @tbl-months and @fig-months. The last chunk shows its code (echo: true) because the way the overdue loans are computed is part of what a reader of the report wants to check.

Source: Quarto documentation: Using R

The data are read with read.csv("books.csv") and read.csv("loans.csv", colClasses = "character"), the way every page of this section reads them, and the dates are parsed with as.Date() in the first chunk; the cleaning of the messy member names is reduced to trimws(), tolower() and tools::toTitleCase(), enough to group Ana Ruiz together with ana ruiz followed by a space and to drop the loan whose member is empty. Rendering is one command, run in the project directory, and the next block shows it with what it prints.

Source: Quarto documentation: Using R

Source: Quarto documentation: Using R

The output is Quarto’s progress report. Lines such as 4/9 [tbl-months] come from knitr, which splits the document into nine pieces (text pieces and chunks alternate, and the label of a chunk is shown when it has one; the chunks without a label would show unnamed-chunk-1). The line output file: report.knit.md names the intermediate Markdown file that knitr wrote, which Quarto deletes after the conversion unless --debug is given. The pandoc block lists the Pandoc settings Quarto chose for the html format, and the metadata block the document metadata it passed on (the title; the options that Quarto handles itself, such as params and execute, are not in the list). The last line names the result. The directory now has the report and the directory with its support files:

Source: Quarto documentation: Using R

Source: Quarto documentation: Using R

report.html is the report and report_files holds what it needs: the figure as figure-html/fig-months-1.png and the CSS and JavaScript of the page in libs. The HTML file is about 25 kB and loads those files, so it has to be moved together with its directory; the option embed-resources: true of the HTML format makes a single self-contained file instead (the older name of the idea in R Markdown is self_contained). The rendered page has the title, the paragraph with its computed numbers (17 loans from 2026-01 to 2026-06-30 of the 16 books in the catalogue), a captioned table and figure that the text refers to by number, the code of the overdue chunk, a table of the six members with overdue loans, and a last sentence with the totals (12 of the 17 loans were overdue). The report that came out is the one shown, as Markdown, in the section on GitHub Markdown below.

A few rules explain most of what happens in a render and most of the surprises.

The document is evaluated top to bottom, in one R session and one environment: a variable created in an early chunk exists in later chunks, so the order of the chunks matters, and nothing is saved between renders unless caching is on. Quarto starts a new R process for every render, so objects of an interactive session are not visible to the document, and a render starts from a clean state, which is the point of a report. rmarkdown::render() is different: its argument envir defaults to parent.frame(), so called from the console it evaluates the chunks in the calling environment, where the console’s objects are visible and the document’s objects are left behind. The help page suggests new.env() to guarantee an empty environment, and rendering from a script run with Rscript (as the R Markdown examples below do) avoids the problem. Code that works in a render only because of an object defined earlier in the console is the most common reason for a report that cannot be reproduced.

The working directory is the directory of the document. That is why read.csv("books.csv") finds the file, and why a document that is moved without its data fails. The help page of knit() says it so: the working directory when evaluating chunks is the directory of the input document by default, it is possible to change it with the package option opts_knit$set(root.dir = ...), and changing it with a call to setwd in a chunk is not recommended, because figure and cache files may be written to the wrong places. Quarto has its own switch for a project: execute-dir in the project key, whose values are file (the directory of the document being executed) and project (the root of the project). The quarto render option --execute-dir sets it for one render.

Everything the code writes to the standard output, standard error, the graphics devices and the condition system is collected: output text becomes a block after the chunk, a message, warning or error is inserted as text, and a plot becomes an image file in the support directory. A chunk that fails stops the render with the chunk’s label and line numbers unless the error is allowed to continue; both cases are shown in the sections on chunk options and on errors.

Quarto finds R on the system PATH (the Quarto documentation names the environment variable QUARTO_R for pointing it to another installation), and needs the rmarkdown package, which brings knitr with it. The command quarto check reports what it found. Its output has many lines with paths; this is the part about the versions used on this page:

Source: Quarto documentation: Using R

Source: Quarto documentation: Using R

(The command printed more lines, with installation paths, progress spinners and the checks for Jupyter and Julia, and they were left out.) The listing shows that Quarto 1.10.19 carries Pandoc 3.10.0, Dart Sass, Typst 0.15.1 and the Deno runtime, that no TeX distribution is installed, and that knitr 1.52 and rmarkdown 2.32 were found. The Pandoc that Quarto uses is not the one on the PATH; rmarkdown, in the section on R Markdown below, reports the other one.

A code chunk starts with three backticks and the language in braces, {r} for R, and ends with three backticks. What happens to it is controlled by chunk options. There are two places to write them.

Source: Quarto documentation: Using R

The first chunk is the R Markdown form, in the header line after the language: a label (the first unnamed item), then name=value pairs separated by commas, with R syntax for the values. The second is the Quarto form: comment lines at the top of the chunk that start with the characters hash and pipe (#|), with YAML syntax for the values. The Quarto documentation explains why: long options such as captions are easier to write on their own line, and editors that do not understand chunk headers can still edit the options. The form is not Quarto’s invention. It is a feature of knitr since version 1.35, whose NEWS says that options written inside a chunk after #| override the same options in the header, so the hash-pipe form also works in R Markdown documents, with either YAML syntax or the comma-separated syntax of the header. The comment character is that of the language of the chunk: knitr 1.51 made a pipe comment in a chunk follow it, and the next block of this section shows what that means for a sql chunk. A value that has to be computed is written with !expr, which is a YAML tag: the Quarto documentation gives #| fig-cap: !expr 'paste("Air", "Quality")'. The Quarto FAQ adds that !expr works inside chunk options and not in the YAML header of the document or the project, and that !r (the R Markdown spelling) is not accepted by Quarto’s validation anywhere.

Quarto also translates names. In its own spelling, the words of an option are separated by hyphens (fig-width, out-width, fig-cap), because Quarto follows Pandoc and YAML conventions, and knitr’s dotted spelling (fig.width) is accepted as well. The next document uses both on two chunks that draw the same figure; the first gives the hyphenated names, the second the dotted ones, and the output document is the same for both.

Source: Quarto documentation: Code Cells: Knitr

Source: Quarto documentation: Code Cells: Knitr

In both chunks the caption became the alternative text of the image, and out-width: 50% became a width of half of the line (the format: gfm output keeps the HTML img tag because plain Markdown has no width). The figure itself is a PNG file in a figures_files directory next to the document.

Numbers in prose are where reports go stale, so they are computed too. Inline code is an expression in the middle of a sentence, between single backticks. There are two syntaxes for R. R Markdown uses the form with a backtick, the letter r, a space, the expression and a closing backtick. Quarto 1.4 added a form that is the same for all engines: the language in braces, as in a chunk, then the expression. Both work in a Quarto document with knitr, and the report uses the second. The difference is in how the result is treated: the Quarto form treats the result as text and escapes any Markdown in it, while the knitr form treats the result as Markdown, which the Quarto documentation says is equivalent to wrapping the expression in I(). The next document shows the two forms, the effect of I(), the escape for documenting the syntax, the knitr: key of the header that sets the options of all chunks, and the Quarto shortcode for including another file.

Source: Quarto documentation: Inline Code

Source: Quarto documentation: Inline Code

Reading the result: both forms gave 60; the Quarto form escaped the asterisks of **bold** (they appear as \*\*bold\*\* in the Markdown, so the reader sees two asterisks on each side), the knitr form made the word bold, and I() restored that in the Quarto form. The extra backtick and the doubled braces both turn the example into text that is not evaluated, which is how the Quarto documentation writes about the syntax, and the shortcode {{< include intro.md >}} inserted the file (it needs no chunk, unlike the child option). The knitr: key in the header is the way to give the whole document the options collapse: true and comment: "#>", and the output shows #> in the first chunk.

The rules to remember are the ones in the Quarto documentation. Keep inline expressions simple, confined to values already computed in chunks, because the protocol they use is not compatible with some libraries. Inline code cannot be used in the YAML header, so a title or a figure caption that must contain a computed number cannot use it; for a caption the documentation recommends combining inline code with the cross-reference div syntax, and a chunk option can take a computed value with !expr. The inline expressions of a document with no executable chunk are not evaluated unless the engine is set explicitly. And a result is formatted as R formats a single value, so format() and round() decide what the reader sees: {r} nrow(recent) is an integer, but the share of overdue loans needs round(100 * mean(...)) or format().

The version history is short. The form with the letter r is knitr’s own and the one in all older tutorials. The 1.4 release notes of Quarto (January 2024) list support for executing inline expressions, with the Python spelling as the example, under the Jupyter engine; the Inline Code article documents the single {lang} syntax for all engines, with {r} for knitr, and says that the native knitr syntax stays supported. This page ran the {r} form on Quarto 1.10.19 and does not claim in which 1.x release it started to work for knitr documents.

A parameterized report is a document with inputs. The monthly report is the example: it is the same document every month, and only the first month to include changes. Parameters are declared in the YAML header with default values, as report.qmd does:

Source: Quarto documentation: Parameters

In the code, the values are the list params, so params$since is "2026-01". For the knitr engine, Quarto uses the standard knitr params YAML option (for Jupyter it uses a cell tagged parameters, in the style of Papermill, and for Julia the keys become variables). The default is a character string and not a number, and it is quoted in the YAML for that reason: the comparison with the month strings of the loans is a comparison of text.

To render with other values, pass them on the command line with -P (--execute-param), one key:value for each parameter, or put them in a YAML file and give it to --execute-params. Each command writes to a different file with --output, so that the first report is not overwritten. The file params-2026-03.yml has the single line since: "2026-03".

Source: Quarto documentation: Parameters

Source: Quarto documentation: Parameters

(The two transcripts are shown one after the other, with the list of metadata shortened.) Both reports start with "This report covers the loans made from 2026-03 to 2026-06-30: 10 loans of the 16 books in the catalogue." The first command shows how --output appears in the Pandoc line.

What a wrong parameter looks like is useful to know, because the message comes from R, not from Quarto. A parameter that the document does not declare is rejected, and so is any use of params in a document that has no params key:

Source: Quarto documentation: Parameters

Source: Quarto documentation: Parameters

The message is render params not declared in YAML: until. It comes from the rmarkdown function knit_params_get(), which the traceback names: Quarto’s knitr engine calls the same code, and it checks the names against the declared parameters. The reverse mistake, a chunk that reads params$since in a document with no params key, stops the render at the chunk. This is the document no-params.qmd from the test directory, which has one chunk labelled use-since whose only line is params$since:

Source: Quarto documentation: Parameters

The error is the plain R error object 'params' not found, followed by the line range and the label of the chunk. A parameter that is declared but not given a value on the command line takes its default, so a report with parameters always renders, which is convenient and also a way to publish a report with stale defaults; the default should be the value the report is normally made with, or the report should stop if it is missing.

The format is chosen in the header, with the format key in Quarto (output in R Markdown), or for one render on the command line with --to. Quarto’s format names follow Pandoc’s, and so do their options, with hyphens instead of underscores. The table compares the two systems for the formats this page produced or tried; the Quarto FAQ for R Markdown users has the full correspondence, including bookdown, blogdown, xaringan, flexdashboard and distill, packages of the R Markdown family that are not installed here and that Quarto replaces with its own books, websites, slides and dashboards.

Source: Quarto documentation: FAQ for R Markdown Users

The command-line form of the choice appears in all the examples below. A document can also list several formats under format:, and quarto render without --to then renders every format listed (the Quarto documentation says the command renders all formats in the document YAML, and renders HTML when none is given).

A chunk that fails is the most common problem in a render, and the two systems treat it the same way. By default the render stops at the first error, names the chunk and the lines, and writes no output. The document fails.qmd has one chunk, labelled read-loans, that reads a file that does not exist:

Source: Quarto documentation: Execution Options

Source: Quarto documentation: Execution Options

Source: Quarto documentation: Execution Options

The error is R 4.6’s: the message cannot open the connection with the call file() and a backtrace (the symbols are the Unicode box characters that rlang prints), then the line that matters for the document: Quitting from fails.qmd:6-9 [read-loans], the file, the lines of the chunk and its label, and Execution halted. The warning that read.csv() also raises about the missing file does not appear because the error stopped the render first. Quarto adds WARN: Error encountered when rendering files and the exit status is 1. The label in the message is the reason to name the chunks; an unlabelled chunk is reported as unnamed-chunk-1, which tells the reader nothing in a long document.

Sometimes the error is the point of the page, for example in a tutorial, or when a chunk is allowed to fail. The option error: true (error = TRUE in R Markdown) keeps the error in the output and continues. The document error-true.qmd has the same failing call:

Source: Quarto documentation: Execution Options

Source: Quarto documentation: Execution Options

Source: Quarto documentation: Execution Options

(The transcript of quarto render, which ends with Output created: error-true.md and the exit status 0, is not repeated.) This time both conditions are in the document, the warning from file() first, then the error, and the text after the chunk follows. The Quarto documentation notes that error: true implies that errors in the code do not stop the processing of the document; the exit status of the render is 0, so a pipeline sees a green build over a page that contains an error. Use it on a chunk that is meant to fail, not on a document, and look at the output. include: false and error: true do not combine well: knitr stops on errors in a chunk whose output is not included, because the error would be invisible.

The table collects the messages of this page, which are all real.

Source: Quarto documentation: Execution Options

A Quarto project is a directory with a _quarto.yml file. The project gives four things, according to the documentation: a way to render all or some of the files of a directory with one command, a way to share YAML options between documents, the ability to redirect the outputs to another directory, and the ability to freeze rendered output so that documents are not re-executed unless they changed. A project has a type: default (a set of documents), website, book or manuscript (the documentation also lists blog and confluence among the choices of quarto create project), and the type adds behaviour: a website has navigation and a search box, a book has chapters and cross-references. Documents do not need a project, as the render of report.qmd above shows; a project is for several documents, or for options that should apply to all of them.

The project file for the shelf report is the smallest useful one. It names the document to render, so that other .qmd files in the directory (a draft, a test) are not rendered; it gives all HTML documents a table of contents; and it freezes the execution of the documents.

Source: Quarto documentation: Project Options

The options come from the documentation. Under project: type, render (the files to render; the default is all valid input files, apart from those whose name starts with a dot or an underscore and README files), output-dir, execute-dir, lib-dir, resources, pre-render and post-render scripts, and preview. The format key holds the options for each output format, here toc: true for the HTML of every document of the project, and the execute key the defaults for chunks, here freeze: auto. The render list accepts wildcards and a ! prefix to exclude files, for example "*.qmd" and "!draft.qmd". Document options are merged with the project options: objects and arrays are merged instead of replaced, the document wins on a conflict, and the exception is format: a document that defines format must define the whole list of formats it wants. The order is _quarto.yml, then a _metadata.yml in a directory (the options of the documents under it), then the YAML of the document. A file _quarto.yml.local holds changes that are not for version control, such as execute: cache: true on one machine, and metadata-files includes other YAML files.

In the project directory, with report.qmd, books.csv, loans.csv and _quarto.yml, rendering the project is quarto render without arguments. The transcript shows the Pandoc block with toc: true, which came from the project file:

Source: Quarto documentation: Project Basics

Source: Quarto documentation: Project Basics

(The progress lines before the Pandoc block are the same as in the first render and are left out.) The directory now has, in addition to the outputs, a hidden .quarto directory with Quarto’s own bookkeeping, which belongs in the ignore file of version control, and a _freeze directory, which does not:

Source: Quarto documentation: Managing Execution

Source: Quarto documentation: Managing Execution

(The two listings are the output of the two commands.) With freeze: auto, the results of executing report.qmd are stored in _freeze/report/execute-results/html.json, with the figure beside it. The Quarto documentation advises checking _freeze into version control, so that others can render the project without reproducing the computational environment, and says to delete it when things outside the source change, such as the input data. The second quarto render shows the effect: the source did not change, so the code did not run again.

Source: Quarto documentation: Managing Execution

There is no processing file line and no chunk progress, only the Pandoc conversion. The two values are freeze: true, which never re-renders during a project render, and freeze: auto, which re-renders when the source changes. Note the limit that the documentation gives: freeze applies to project renders, and rendering a single document or a subdirectory always executes the code. So quarto render report.qmd ignores the freeze, and quarto render with the project does not.

Two more commands belong to project work. quarto preview starts a local server, renders the project and re-renders when a file is saved, and opens the result in a browser; it is a fragment here, not run, because it does not end by itself:

Source: Quarto documentation: Project Basics

quarto create project asks for a type and a name and writes a project skeleton (the types are default, website, blog, manuscript, book and confluence), also a fragment. The listing of the options of quarto render is useful to have close; it is the real text of the program’s help, with the trailing blanks removed:

Source: Quarto documentation: Project Basics

Source: Quarto documentation: Project Basics

The options used on this page are --to, --output, -P/--execute-param and --execute-params, --cache/--no-cache/--cache-refresh, --quiet, --debug and, for rendering without running the code, --no-execute. --execute-dir and --output-dir repeat the project options for one render, and --profile selects a project profile, the mechanism by which one project has a development and a production configuration.

R Markdown is the older of the two systems, and it did not stop when Quarto appeared. The Quarto FAQ for R Markdown users says it plainly: R Markdown is not going away, it will continue to be actively supported, everything that is in it will continue to work, and there are no plans to deprecate it; it also says that no major feature initiatives are planned for R Markdown and its related packages, which keep being maintained (smaller improvements and bug fixes) for a long time, that some new features may exist only in Quarto, that there is no need to switch, and that switching is cheap, because most .Rmd files render unmodified with Quarto. The facts agree with that: rmarkdown 2.32 was published on CRAN on 2026-09-01 and knitr 1.52 on 2026-09-06, and the rmarkdown NEWS for 2.32 lists fixes (LaTeX auxiliary files written to the output directory, a fix for intermediates_dir, render() in a forked cluster), a new minimum Pandoc of 2.8 and a change of the licence to MIT. The R Markdown ecosystem (bookdown for books, blogdown for sites, xaringan for slides, flexdashboard for dashboards, distill for articles) is the part that Quarto replaces with built-in features; those packages are separate and none was run on this page. All but distill had a CRAN release in the last year (distill’s last release is from 2023), as the CRAN pages show. A rule of thumb that follows from this: keep the documents you have as they are, and start a new project in Quarto when it needs a feature that only Quarto has, such as its projects, its cross-references or Typst.

The R Markdown twin of the report differs from report.qmd only in syntax. The header uses output: with the function html_document and its option toc: true; the options of the chunks are in the header line ({r setup, include=FALSE}, {r months-plot, fig.cap="Loans per month.", fig.width=6, fig.height=3}); the echo = FALSE default comes from knitr::opts_chunk$set() in the setup chunk; the inline code is the knitr form; the caption of the table is the caption argument of kable(); and there are no cross references, because that feature belongs to Quarto and to the bookdown package.

Source: R Markdown documentation: Introduction

An R Markdown document is rendered with rmarkdown::render(), from a script or the console. The script renders the twin to report-rmd.html, so that it does not overwrite the Quarto report, and checks that the file exists. quiet = TRUE hides the Pandoc command line and the progress bar.

Source: R Markdown documentation: render

The arguments of render() are the knobs of the system, and printing them is the quickest reference. The script also reports the version of Pandoc that rmarkdown found, and reads back what the document says about itself with yaml_front_matter() and all_output_formats().

Source: R Markdown documentation: render

The sixteen arguments include output_format (a name such as "word_document" or an object such as html_document(toc = TRUE)), output_file and output_dir (the file name and the directory of the result), output_options (a list that overrides the format’s options), params, envir (the environment the chunks are evaluated in, parent.frame() by default, as discussed above), knit_root_dir (the working directory to knit in; by default the directory of the document), intermediates_dir, clean, run_pandoc and quiet. The Pandoc that rmarkdown used is 3.1.3, the system’s, and not the 3.10.0 of Quarto: the two systems can differ in small details of the HTML or Word output for the same Markdown, and a document that is rendered by both should be compared. The functions yaml_front_matter() and all_output_formats() return the header as a list, with the parameter default and the toc option, and the vector of the formats the document asks for.

The inverse of weaving is tangling: extracting the R code of a document into a script. knitr::purl() does it, as Stangle() does for Sweave files. It is the tool for running the code of a report without rendering it, for debugging it with the usual tools of Debugging, and for linting it. The script tangles the twin with the default level of documentation, which adds a comment with the chunk header before each chunk, and the Quarto document, where the hash-pipe options are kept as comments (since knitr 1.44). Only the first lines of each are shown.

Source: knitr package documentation: purl

Two details deserve attention. The tangled script starts with params <- and the default values of the parameters, so the script runs on its own with the defaults; and inline expressions are not included in the script, because the option knitr.purl.inline that includes them is off by default, according to the help page of knit(). A chunk can opt out with purl = FALSE (Quarto: purl: false). With documentation = 0 only the code is written; with documentation = 2 the text of the document is written as roxygen comments, which is a way to turn a report into a documented script.

Sweave is the original weaving system of R, and it ships with R, in the utils package. It processes .Rnw files, which are LaTeX documents with R code, and it is the format that the manual section on package vignettes is written around. A chunk begins with <<label, options>>= at the start of a line and ends with @ at the start of a line; an inline expression is \Sexpr{...}. The file for the shelf is the smallest example that has a chunk with its code and result, an inline expression and a chunk with echo=FALSE:

Source: Writing R Extensions: Writing package vignettes

Sweave() runs the code and writes a .tex file; it does not run LaTeX, which is why it works without a TeX installation. Stangle() writes the R code. The script writes both to temporary files and prints them (quiet = TRUE hides the messages that name the files):

Source: R documentation: Sweave

The .tex file has the LaTeX package Sweave loaded (\usepackage{Sweave} inserted after the document class), the code in Sinput environments with the prompts >, the output in Soutput, and the whole in a Schunk. The tangled script is plain R code with a comment for each chunk. Both belong to the RweaveLatex driver, the default driver for weaving, and Rtangle, the one for tangling; the help page RweaveLatex documents the chunk options: engine, echo, keep.source, eval, results (verbatim, tex or hide), print, term, split, strip.white, prefix, include, and, for figures, fig (only one figure per chunk can be produced this way), pdf, png, eps, jpeg, width and height. The Sweave help page adds that Stangle() is a wrapper to Sweave() with a different default driver, and that code inside \Sexpr{} is ignored by it, and that the environment variable SWEAVE_OPTIONS can override the initial options of the driver. Sweave has fewer options and fewer formats than knitr: the default driver writes LaTeX only. The command-line forms are R CMD Sweave and R CMD Stangle, which write the files into the current directory:

Source: R documentation: Sweave

Source: R documentation: Sweave

(The output of the three commands, in order.) R CMD Sweave wrote shelf.tex, R CMD Stangle wrote shelf.R, and the data file and the source are as they were. To go on to a PDF, R CMD Sweave --pdf runs LaTeX on the result, which needs TeX; without it:

Source: R documentation: Sweave

Source: R documentation: Sweave

The first line is a warning that the texi2dvi program was not found and R used its emulation, and the error says that pdflatex is not available; the exit status is 1. The usage text of the two commands, as printed by R, lists their options; those of R CMD Sweave are --driver, --engine, --encoding, --clean, --options, --pdf and --compact:

Source: Writing R Extensions: Writing package vignettes

(The two help texts, one after the other; the "Report bugs at" line that ends each of them is omitted.) The options --engine and the text "and other vignette engines" show that the two commands are no longer only for Sweave: since R 3.1.0 they process vignettes of any engine registered by a package, and tools::buildVignette() does the same from R, according to the R 3.x NEWS. knitr can process an .Rnw file too, with its own LaTeX output, and knit() was used for this above. The script runs knit() on the same file and prints the part of the result after the preamble, which shows the way knitr marks up the code and the output (the long preamble of definitions for the syntax highlighting is left out):

Source: knitr package documentation: knit

The result has knitrout and kframe environments instead of Schunk, the code is highlighted by LaTeX macros (\hlkwd{read.csv}), and the output lines have the knitr prefix ##. That is the difference in miniature: the document is the same, the engine is knitr, and the options and the look come from knitr. The cost of Sweave and .Rnw is that everything, including the text, is LaTeX, so a web page, a Word file or slides need a different source. Sweave is still supported and is still the format that the manual Writing R Extensions describes, with an engine utils::Sweave that needs no VignetteBuilder field; other engines are named by the package that provides them, and Non-Sweave vignettes is the section that explains how.

A package vignette is a report that is a part of a package, and it is built when the package is built. The shelf package has one, vignettes/shelf.Rmd, which is an R Markdown document with the header lines that R reads (%\VignetteEngine{knitr::rmarkdown}) and the field VignetteBuilder: knitr in DESCRIPTION; Documentation with Rd, roxygen2 and Vignettes shows the file and builds it, and Creating Packages the package. A vignette in Quarto uses VignetteBuilder: quarto in DESCRIPTION, quarto in Suggests and the engine %\VignetteEngine{quarto::html} in the .qmd file; the quarto R package, which provides the engine and quarto_render(), is not installed in the image, so that route is described and not run (the documentation page shows the Quarto program rendering such a file by hand). The quarto package version on CRAN at the time of writing is 1.5.1.

For a vignette the choice between the systems is practical. knitr with R Markdown has no dependency outside R and Pandoc, and is the default of the package tooling. Quarto vignettes need the Quarto program on every machine that builds the package, and are best kept for a package whose other documentation is already in Quarto.

Source: R NEWS: Changes in R 4.2.0 and Changes in R 4.6.0

Source: R NEWS: Changes in R 3.1.0

Source: knitr NEWS

Source: rmarkdown NEWS

Source: Quarto documentation: Quarto 1.4 release notes

Source: Quarto documentation: Download Quarto

The R 4.2.0 and 4.6.0 entries come from the NEWS of those releases and are about Sweave only. The Quarto and knitr facts come from their release notes and NEWS files, read on 2026-10-21; the Quarto release dates are those of the GitHub releases (1.4.549 on 2024-01-24, 1.10.19 on 2026-10-06, 1.11.6 on 2026-10-14). Posit’s tools change faster than R itself; anything on this page that depends on a Quarto or knitr feature should be rechecked against the versions on the reader’s machine, which quarto --version and packageVersion("knitr") report.

Source: knitr package documentation: knit2html

Source: Quarto documentation: FAQ for R Markdown Users