knitr 1.31

NEW FEATURES

• Exported the functions pandoc_to() and pandoc_from() to get the output and input Pandoc format respectively when knitting R Markdown documents (thanks, @cderv, #1951).

• Added a new chunk option fig.alt for users to specify the alternative text in the alt attribute of the <img> tag (images). Previously, the alt attribute takes value from the chunk option fig.cap (it still does so if fig.alt is NULL). If there are multiple plots/images in a chunk, you can pass a character vector to fig.alt, and it will be applied to individual images (thanks, @cderv, #1900).

• include_url() and include_app() can now take a vector of URLs (thanks, @cderv, #1948).

• The sql engine now correctly captures error with the chunk option error = TRUE (thanks, @colearendt, rstudio/rmarkdown#1208).

• The chunk option collapse = TRUE now works as expected when the chunk option attr.* or class.* is provided. By this change, The chunk option collapse = TRUE forces attr.* and class.* be NULL except for the chunk options attr.source and class.source (thanks, @aosavi @cderv @atusy, #1902 #1906).

• New links added in ?knitr::kable() help page to the Rmarkdown Cookbook relevant pages.

• The table label can be disabled via kable(label = NA) now (thanks, @NickCH-K, #1937).

• The table.attr argument in kable(.., format = 'html') can take the value from the global option knitr.table.html.attr now (thanks, @cderv, #1922).

• Added a new argument oxford_comma to the function combine_words() (thanks, @thompsonsed, #1946).

• The label prefix of tables generated by kable() can be customized via the package option label.prefix in opts_knit now. This option takes a named character vector, and the default is knitr::opts_knit$set(label.prefix = c(table = 'tab:')). If you want to use a different prefix such as tbl, you may set the option to c(table = 'tbl:') (thanks, @luispfonseca, #1890).

• The global option options(knitr.device.fallback = TRUE) can be used to allow the graphical device specified in the chunk option dev to fall back to other usable devices if the specified device is not operational. Users can provide a list of fallback devices via the global option, e.g., options(knitr.device.choices = list(png = c('jpeg', 'svg'), jpeg = c('tiff'))), which means the png device can fall back to jpeg and svg (the first operational device in the list is used) and jpeg can fall back to tiff.

BUG FIXES

• Line numbers in error messages are incorrect when the error occurs in a child Rmd document (thanks, @cderv @khughitt, #1945).

MAJOR CHANGES

• Previously knit_exit() in a child document would not terminate the knitting process of its parent document. Now it will terminate the whole process by default. You can use knit_exit(fully = FALSE) to exit the child document only (thanks, @davidchall, #1810).

MINOR CHANGES

• Vignette engines for R Markdown vignettes no longer check for availability of pandoc-citeproc since it has gone since Pandoc 2.11.

knitr 1.30

NEW FEATURES

• Added knitr::hooks_*() functions to get a list of output hooks for a specific format. Previously, these hooks only exist inside the knitr::render_*() functions, and users do not have direct access to them. Now they can be accessed directly, e.g., via knitr::hooks_markdown() to get a list of output hooks for R Markdown documents. You can also set the output hooks individually, e.g., knitr::knit_hooks$set(knitr::hooks_markdown()['source']) only sets the source ouput hook. See more on output hooks at https://yihui.org/knitr/hooks/#output-hooks and https://bookdown.org/yihui/rmarkdown-cookbook/output-hooks.html (thanks, @cderv, #1889).

• Added an argument lib.loc to knitr::write_bib().

BUG FIXES

• The option fig_caption = FALSE for rmarkdown::html_document() was unable to suppress the figure captions in some cases.

• The internal function fix_options() should be called after option hooks are executed (thanks, @atusy, #1876 and #1877).

• When the option options(OutDec = ) is set to a value other than ".", percentages in the chunk options out.width and out.height do not work (thanks, @omgitsmoe, #1887).

MINOR CHANGES

• knitr::write_bib() removes pairs of single quotes in the titles of citation entries now.

• knitr::write_bib() uses the URL in the package DESCRIPTION if it is provided, instead of the canonical CRAN URL for the package.

• hook_pdfcrop() and plot_crop() will work only when both programs pdfcrop and ghostscript have been installed. Previously only pdfcrop was checked (thanks, @dalupus, #954).

knitr 1.29

NEW FEATURES

• Added a new function kables() (the plural form of kable()) to create a table containing multiple tables, with each table created by kable(). Previously you can only create such a table from kable(list(data1, data2)), and now you can also do kables(list(kable(data1), kable(data2))). The latter way gives you more freedom to control each table individually via the arguments of each individual kable() call.

• The graphics device chunk option, dev, now supports a value of 'ragg_png' which calls the agg_png() function from the ragg package (thanks, @cpsievert, #1834).

• The argument error of include_graphics() takes value from the global R option knitr.graphics.error by default, e.g., you may set options(knitr.graphics.error = FALSE) so include_graphics() won't signal an error if the graphics file to be included doesn't exist.

• Added a new engine cc to compile C++ code via R CMD SHILIB like the c and fortran engines (thanks, @kingaa, #1832).

BUG FIXES

• For non-R code chunks that generate plots and use the chunk option fig.cap, the plot hook in knitr stopped working in v1.27 and v1.28 (thanks, @XiangyunHuang, https://d.cosx.org/d/421249).

• The sql engine fails when the first column of the database is of the type bit64::integer64 (thanks, @randy3k, #1837).

• The chunk option dpi is correctly passed to showtext::showtext_opts() now (thanks, @cpsievert, yixuan/showtext#33).

• Theorem environments in bookdown fail to work with Pandoc >= 2.7.3 because of an issue in the block2 engine of knitr (rstudio/bookdown#883).

MAJOR CHANGES

• For R Markdown documents, the default table format generated by kable() was changed from Pandoc's simple tables to pipe tables. This fixes bugs #1788 (kable() fails to align columns containing wide characters) and #1817 (broken column headers) (thanks, @atusy, #1830).

• When a code chunk generates multiple plots to be placed in figure environments, their figure labels will be of the form label-i where label is the chunk label, and i is the plot number. Previously, the labels were of the form labeli (i.e., there was not a dash before the number). If you cross-reference the figures, you need to change the reference keys from labeli to label-i.

• For a non-matrix object passed to kable(), its columns are formatted individually via format(). Previously, the whole object is coerced via as.matrix() (thanks, @thebioengineer, #1827).

• For packages that contain R Markdown vignettes using the vignette engines based on the markdown package (e.g., knitr::knitr), the markdown package should be declared in Suggests in the package DESCRIPTION unless it has already been declared as a dependency in other fields. For this version of knitr, you will see a warning in R CMD check in the CRAN incoming check. In the future, you may see a warning in a regular R CMD check, so please add markdown to Suggests at your earliest convenience. If it is not clear how to do it, please see #1864.

MINOR CHANGES

• knitr::image_uri() calls xfun::base64_uri() instead of markdown:::.b64EncodeFile() now.

• knitr::write_bib() now adds an empty line after each BibTeX entry (#1862).

knitr 1.28

BUG FIXES

• hook_pdfcrop() no longer crops images included via include_graphics() now (thanks, @hpages #1797, @salim-b #1800).

MAJOR CHANGES

• If the hook_pdfcrop() is enabled, the non-PDF image will be cropped only if the magick package is available, otherwise it will signal a message. In the previous version, it will signal an error (thanks, @trannhatanh89, #1796).

• By default, include_graphics(files) will signal an error if any files do not exist and are not web resources. To avoid the error (e.g., if you think it is a false positive), use include_graphics(..., error = FALSE) (thanks, @hadley, #1717).

knitr 1.27

NEW FEATURES

• The chunk option message = FALSE can now be used to suppress the message "running: command ..." when the language engine is a command such as bash, awk, perl, ruby, sas, sed, and stata, etc. (thanks, @splaisan, #1782).

BUG FIXES

• The figure caption was placed incorrectly when there are multiple include_graphics() in a code chunk (thanks, @hadley #1771, @cderv #1776).

• The chunk option fig.keep was buggy when taking a numeric vector. The bug was originally introduced in #1265 and discovered in the SO post https://stackoverflow.com/q/59180351/559676.

• When the chunk option dev = 'tikz' and a plot in the code chunk is generated by ggplot2 with a legend on a continuous scale, tikzDevice will create a raster image for the legend. Now the path to the raster image in the .tex file is tweaked to include the dir name of the .tex file, so that the .tex file can be correctly compiled to PDF via LaTeX (thanks to @rstub for the debugging at https://stackoverflow.com/a/58410965/559676).

• hook_pdfcrop() does not crop all plots when multiple graphical devices are used in a code chunk (i.e., the chunk option dev takes a vector of devices) due to a bug in the internal function all_figs() identified by @bastistician in #1766, who also proposed a fix.

MAJOR CHANGES

• options('width') no longer affects caching. With this change, your previous cache will be invalidated if you update knitr from 1.26 to 1.27. If you prefer that changes in the R global option width invalidate cache (as in previous versions of knitr), you may associate it with a chunk option, e.g., cache.extra = getOption('width'). The reason for this change is that it is too costly to invalidate the cache when the width option changes---the effect of this option is only cosmetic and the code chunk output may not really rely on this option (thanks, @jaburgoyne, #1781).

MINOR CHANGES

• is_html_output() returns TRUE for the Pandoc output format gfm now (thanks, @ttimbers @cderv, rstudio/rmarkdown#1756).

• plot_crop() no longer calls the convert command in ImageMagick to trim non-PDF plots. Instead, the function magick::image_trim() is called. This means you no longer need to install ImageMagick, but should install the R package magick (thanks, @hpages, #1785).

• When the chunk option fig.scap is used in R Markdown and the output format is LaTeX/PDF, the plot hook knitr::hook_plot_tex() will be used to create the appropriate figure environment. In previous versions, fig.scap is silently ignored (thanks, @billdenney, #1793).

knitr 1.26

NEW FEATURES

• write_bib() also includes all citation entries in the package's CITATION file if provided.

MINOR CHANGES

• knit() no longer adjusts the global R option width; previously it sets options(width = 75) by default.

knitr 1.25

NEW FEATURES

• Office outputs (e.g., rmarkdown::word_document) supports the following chunk options out.width, out.height, out.extra. Their behavior follows the behavior of Pandoc's link_attributes extention (thanks, @atusy, #1746).

• The chunk option fig.process can be specified by a function with the options argument to read chunk options (thanks, @atusy, #1749).

• For kable(format = 'latex'), a single string consisting of l, c, and r for the align argument also works now, e.g., knitr::kable(head(iris), 'latex', align = 'llcrr'). Previously it has to be a character vector of individual letters.

MAJOR CHANGES

• Reverted #1519 (which intended to fix #1487): the valign argument of kable(format = 'latex') meant to control the vertical alignment of the inner tabular environment, instead of the floating position of the outer table environment. A separate argument named position has been added to control the floating position (e.g., position = "!b").

MINOR CHANGES

• The returned value of combine_words() is wrapped in xfun::raw_string() for pretty printing.

BUG FIXES

• The output hook for render_sweave() failed to respect the chunk option results='asis' (thanks, Achim Zeileis, https://stackoverflow.com/q/57571790/559676).

• Added the unit px to the chunk option out.width if its value is numeric (thanks, @chendaniely, #1761).

• The chunk option dependson did not work for non-R engines (thanks, @nielsrhansen, #1601).

knitr 1.24

MAJOR CHANGES

• The input argument of knitr::knit() must be a file path (a character string). It can no longer be connections.

• The encoding argument of knitr::knit() is ignored. The encoding is always assumed to be UTF-8. Please see https://yihui.name/en/2018/11/biggest-regret-knitr/ for more info.

BUG FIXES

• Inline code chunk references are parsed as character vectors instead of single character strings separated by \n now. This will avoid errors when a python code chunk contains a reference to a code chunk that contains multiple statements (thanks, @Atrebas, rstudio/rmarkdown#1589).

knitr 1.23

NEW FEATURES

• Added mogrify support in hook_png() and hook_mogrify() in order to obtain trimmed .png files (thanks, @mhofert, #1697).

• It is possible to customize the sign \times used for the scientific notation of inline numeric output via a global option, e.g., options(knitr.inline.times = '\\cdot ') (thanks, @wuffi @trentks, #1563).

• Exported knit_code and documented it at ?knitr::knit_code. Here be dragons, but I know you are brave and creative (thanks, @r-cheologist @ProQuestionAsker, #1545).

• Added support for specifying fenced code block attributes in Markdown output via chunk options attr.*, which are similar but a generalization to the existing chunk options class.*. For example, class.source = 'numberLines' is equivalent to attr.source = '.numberLines', but attr.source can take arbitrary attribute values, e.g., attr.source = c('.numberLines', 'startFrom="11"') (thanks, @atusy, #1710).

BUG FIXES

• For R Markdown documents, inline numeric output that is formatted with the scientific notation will be wrapped in \ensuremath{}. This will fix the LaTeX error ! Missing $ inserted.. However, you are still recommended to add a pair of dollar signs around the inline output when it is formatted with the scientific notation (e.g., $`r 1.234e12`$), otherwise it will not work with other R Markdown output formats such as HTML or Word (thanks, @billdenney and many who have suffered from this issue, rstudio/rmarkdown#1527).

• For an input file that contains no code chunks or inline R code expressions, purl() should return an empty string instead of the original text from the input (thanks, @jrnold, #1660).

• purl() might trigger a warning for non-R code chunks (thanks, @adamcagle, rstudio/rmarkdown#1528).

• When building package vignettes via R CMD build, the R scripts generated from knitr's vignette (tangling) engines are not corrected encoded in UTF-8 (thanks, Kurt Hornik).

• Fixed a bug introduced when fixing #1648: include_url() no longer works at all unless the chunk option out.extra is not empty (thanks, @gabrielvazdemelo, #1691).

• When evaluating perl code chunks the interpreter is spawned with the -E option, enabling all optional features such as say, rather than -e (thanks, @kiwiroy, #1699)

• When the chunk label of a tikz chunk contains periods, the tikz output cannot be converted to the expected .svg (thanks, @ucpresearch, #1706).

• The ... argument for raw_latex() and raw_html() is actually passed to asis_output() now (thanks, @GregorDeCillia, #1716).

MAJOR CHANGES

• knitr::knit() will try to read the input file with the UTF-8 encoding first. If UTF-8 doesn't work, it will try to read with the system native encoding instead (with a warning). The encoding argument of knitr::knit() is completely ignored. In the future, only UTF-8 will be supported, and we will stop retrying with the system native encoding. The output file from knitr::knit() is always encoded in UTF-8.

• spin_child() will also assume the input file is encoded in UTF-8 (thanks, Henrik, https://stackoverflow.com/q/55395422/559676).

• When the chunk option dev = 'svg', grDevices::svg() is used to record plots, instead of the default PDF null device (thanks, @trevorld, #729).

• Partially reverted the solution for #1403 in favor of fixing the more surprising issue #1708, i.e., avoid false positive cache dependencies among chunks more than false negative dependencies when the chunk option autodep = TRUE (thanks, @fountainer).

• The LaTeX package framed.sty is no longer bundled with the knitr package. This should only affect users who write .Rnw documents. If framed.sty is missing in your LaTeX distribution, you will have to install it by yourself. You may also consider TinyTeX (https://yihui.name/tinytex/), which has included this LaTeX package.

knitr 1.22

NEW FEATURES

• Added chunk options class.error, class.warning, and class.message to customize the CSS classes for errors, warnings, and messages in R Markdown output, respectively (thanks, @gadenbuie, #1676).

• Added a new engine sass/scss to convert Sass/SCSS to CSS using either the sass R package (LibSass) or Dart Sass executable (when R package not found, the engine option engine.opts = list(package = FALSE), or engine.path to executable is provided). After conversion, resulting CSS is treated as in the CSS engine (thanks, @emilyriederer, #1666).

• The cat engine supports the chunk option eval = FALSE now (thanks, @HanOostdijk, #1618).

• The chunk option out.extra can be used to include extra attributes for the <iframe> generated from knitr::include_url() or knitr::include_app() (thanks, @jvcasillas, #1648).

BUG FIXES

• knit_meta_add() could exhaust the system's memory because of a wrong method of vectorization (thanks, @kevinushey @nikkoc, rstudio/rmarkdown#1538).

• The output path should be quoted in pandoc() (thanks, @antoine-sachet, #1644).

• When there are multiple figures with multiple captions in a code chunk, bookdown's figure numbering is incorrect (thanks, Catherine Peng, https://stackoverflow.com/q/53880195/559676).

• Added an argument label to kable() so that users can manually specify a label (thanks, @Inferrator, #1655).

• The chunk option fig.show='hide' doesn't work for knitr::include_graphics() (thanks, @vincentarelbundock, #1675).

• The tikz engine doesn't work on Windows (thanks, Andry, https://stackoverflow.com/q/54839403/559676).

• kable() now generates a table for R Markdown documents even when the data has 0 rows (thanks, @yutannihilation, #1677).

• The chunk options dev = 'tikz' and external = FALSE didn't work in R Markdown (thanks, @martinschmelzer, #1649).

MAJOR CHANGES

• knitr::knit() starts to warn against non-UTF8 encodings (Why?). In the future, we will only support UTF-8 input. If your input file is not encoded in UTF-8, we strongly recommend that you re-save it with UTF-8.

• Removed the encoding arguments in knitr::pandoc(), knitr::knit2pdf(), knitr2wp(), and knitr::Sweave2knitr(). The input files must be encoded in UTF-8.

• knitr::knit2html() still has the encoding argument, but it only supports UTF-8 internally.

MINOR CHANGES

• Changed tools::texi2dvi() to tinytex::latexmk() for the tikz engine to compile TikZ graphics to other foramts (e.g., svg or png). This requires the tinytex package >= v0.10.10: https://github.com/yihui/tinytex.

• Empty lines are no longer removed in the output of purl() (thanks, Marius Hofert).