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