1#' Convert to an HTML vignette 2#' 3#' A HTML vignette is a lightweight alternative to \code{\link{html_document}} 4#' suitable for inclusion in packages to be released to CRAN. It reduces the 5#' size of a basic vignette from 100k to around 10k. 6#' 7#' Compared to \code{html_document}, it: 8#' 9#' \itemize{ 10#' \item never uses retina figures 11#' \item never uses a theme 12#' \item has a smaller default figure size 13#' \item uses a custom css stylesheet 14#' \item uses a custom highlight scheme 15#' } 16#' 17#' See the \href{https://bookdown.org/yihui/rmarkdown/r-package-vignette.html}{online 18#' documentation} for additional details on using the \code{html_vignette} format. 19#' @inheritParams html_document 20#' @param ... Additional arguments passed to \code{\link{html_document}}. Please 21#' note that \code{theme}, \code{fig_retina} and \code{highlight} are hard 22#' coded. Setting any of those will yield an error. 23#' @param css One or more css files to include. 24#' @param readme Use this vignette as the package README.md file (i.e. render 25#' it as README.md to the package root). Note that if there are image files 26#' within your vignette you should be sure to add README_files to .Rbuildignore 27#' @return R Markdown output format to pass to \code{\link{render}} 28#' @export 29html_vignette <- function(fig_width = 3, 30 fig_height = 3, 31 dev = 'png', 32 df_print = "default", 33 css = NULL, 34 keep_md = FALSE, 35 readme = FALSE, 36 self_contained = TRUE, 37 ...) { 38 39 if (is.null(css)) { 40 css <- system.file("rmarkdown", "templates", "html_vignette" ,"resources", 41 "vignette.css", package = "rmarkdown") 42 } 43 44 pre_knit <- function(input, ...) { 45 if (readme) { 46 rmarkdown::render(input, 47 output_format = "github_document", 48 output_options = list(html_preview = FALSE), 49 output_file = "README.md", 50 output_dir = dirname(dirname(input)), 51 quiet = TRUE) 52 } 53 } 54 55 pre_processor <- function(metadata, input_file, runtime, knit_meta, 56 files_dir, output_dir) { 57 vignette_pre_processor(input_file, metadata) 58 } 59 60 output_format( 61 knitr = NULL, 62 pandoc = NULL, 63 df_print = df_print, 64 pre_knit = pre_knit, 65 keep_md = keep_md, 66 clean_supporting = self_contained, 67 pre_processor = pre_processor, 68 base_format = html_document(fig_width = fig_width, 69 fig_height = fig_height, 70 dev = dev, 71 fig_retina = NULL, 72 css = css, 73 theme = NULL, 74 highlight = "pygments", 75 self_contained = self_contained, 76 ...) 77 ) 78} 79 80vignette_pre_processor <- function(input_file, metadata = yaml_front_matter(input_file)) { 81 if (getRversion() < 3.6) 82 return() 83 if (!getOption(o <- 'rmarkdown.html_vignette.check_title', !xfun::is_R_CMD_check())) 84 return() 85 title1 <- metadata[['title']] 86 title2 <- tools::vignetteInfo(input_file)[['title']] 87 # rmarkdown assumes UTF-8 only - tools::vignetteInfo uses readLines with 88 # default OS encoding so issue on Windows for example 89 # https://github.com/rstudio/rmarkdown/issues/1978 90 Encoding(title2) <- "UTF-8" 91 if (!identical(title1, title2)) warning( 92 'The vignette title specified in \\VignetteIndexEntry{} is different from ', 93 'the title in the YAML metadata. The former is "', title2, '", and the ', 94 'latter is "', title1, '". If that is intentional, you may set options(', o, 95 ' = FALSE) to suppress this check.', call. = FALSE 96 ) 97 NULL 98} 99