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).

CRAN release v1.21

NEW FEATURES

• Added styler support: the chunk option tidy = 'styler', the code will be reformatted using the styler package. The chunk option tidy = TRUE means tidy = 'formatR' and still uses formatR::tidy_source() to reformat the code. The chunk option tidy can also take a custom function to reformat the code. See the documentation for details: https://yihui.name/knitr/options/ (thanks, @lorenzwalthert, #1581).

• Added a new hook function hook_gifski() to create a GIF animation from plots in a code chunk. To enable this hook, you may install.packages('gifski') and set the chunk option animation.hook='gifski'. See https://yihui.name/en/2018/08/gifski-knitr/ for examples.

• Added a new object cache_engines for other language engines to handle caching. See ?knitr::cache_engines for details (thanks, @tmastny, #1518).

• Can now pass additional arguments to knitr vignette engines if needed (thanks, @jimhester, #1577).

• When options(knitr.include_graphics.ext = TRUE) is set, the full filename will be used in \includegraphics{} (e.g., \includegraphics{foo.pdf}) instead of the (default) base filename (e.g., \includegraphics{foo}) if a plot is embedded in the LaTeX output. This will avoid the ambiguity for LaTeX to choose the correct file (#1587).

• The chunk option engine.opts can also take a list now, so that users can specify different options for different language engines (thanks, @kiwiroy, #1632).

• Added functions raw_block(), raw_latex(), and raw_html() to wrap content in raw attribute blocks for Pandoc (thanks, @hughjonesd, #1633).

BUG FIXES

• valign in kable_latex() does not put the float alignment to the correct location (thanks, @haozhu233, #1487, #1519).

• engine.path does not work for engine = 'dot' (thanks, @billy34, #1534).

• The sql engine now caches the result properly when the chunk option output.var is specified (thanks, @yutannihilation, #1544).

• knit_params() mangles UTF-8 text not representable in current locale (thanks, @kevinushey, #1557).

• The linesep argument in kable(format = 'latex') does not work as expected (thanks, @tinu-schneider, #1558).

• MP4 generated by hook_ffmpeg() does not work in Safari (thanks, @brianzhang01, #1586).

• The chunk option fig.env does not work for PDF output from R Markdown (thanks, @RSchwinn, #1620).

• spin() fails to generate a proper R Markdown document when the R script contains roxygen comments as string literals or more than three backticks (thanks, @yutannihilation, #1605, #1611).

• Stan chunks cannot be properly cached: the bug #1064 appeared again (thanks, Mark, https://stackoverflow.com/q/53660143/559676).

• Roman numerals should not be converted to arabic numerals in inline R expressions (thanks, @rgaiacs, #1625).

MAJOR CHANGES

• For R scripts passed to spin(), only the UTF-8 encoding is accepted (previously it assumes the native encoding of the system).

• Due to changes in the S3 method dispatch mechanism since R 3.5.0, you will have to call registerS3method() to register knit_print methods defined in code chunks. For package authors, it no longer suffices to export a method without importing knitr::knit_print, but if you don't want to import it, there is still a workaround. See the package vignette vignette('knit_print', package = 'knitr') for details (thanks, @wch @kevinushey @skranz #1580).

MINOR CHANGES

• spin() will close each individual code chunk if multiple code chunks appear consecutively (previously it only closes the last code chunk in this case) (thanks, @avehtari, #1590).

CRAN release v1.20

NEW FEATURES

• Added a roxygen_comments parameter to read_chunk() in order to control whether trailing commentary is stripped from code chunks; default behaviour is to keep roxygen comments with roxygen_comments = TRUE (thanks, @ruaridhw, #1484).

BUG FIXES

• knit_filter() does not work for R Markdown input files (thanks, @omahdi, #1498).