/
html_document.R
251 lines (229 loc) · 9.5 KB
/
html_document.R
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
#' Convert to an HTML document
#'
#' Format for converting from R Markdown to an HTML document.
#'
#' @param toc \code{TRUE} to include a table of contents in the output
#' @param toc_depth Depth of headers to include in table of contents
#' @param number_sections \code{TRUE} to number section headings
#' @param fig_width Default width (in inches) for figures
#' @param fig_height Default width (in inches) for figures
#' @param fig_retina Scaling to perform for retina displays (defaults to 2 when
#' \code{fig_caption} is \code{FALSE}, which currently works for all widely
#' used retina displays). Set to \code{NULL} to prevent retina scaling. Note
#' that this will always be \code{NULL} when \code{keep_md} is specified (this
#' is because \code{fig_retina} relies on outputting HTML directly into the
#' markdown document).
#' @param fig_caption \code{TRUE} to render figures with captions
#' @param smart Produce typographically correct output, converting straight
#' quotes to curly quotes, --- to em-dashes, -- to en-dashes, and ... to
#' ellipses.
#' @param self_contained Produce a standalone HTML file with no external
#' dependencies, using data: URIs to incorporate the contents of linked
#' scripts, stylesheets, images, and videos. Note that even for self
#' contained documents MathJax is still loaded externally (this is
#' necessary because of it's size).
#' @param theme Visual theme ("default", "cerulean", "journal", "flatly",
#' "readable", "spacelab", "united", or "cosmo"). Pass \code{NULL} for
#' no theme (in this case you can use the \code{css} parameter to add your own
#' styles).
#' @param highlight Syntax highlighting style. Supported styles include
#' "default", "tango", "pygments", "kate", "monochrome", "espresso",
#' "zenburn", "haddock", and "textmate". Pass \code{NULL} to prevent syntax
#' highlighting.
#' @param mathjax Include mathjax. The "default" option uses an https URL from
#' the official MathJax CDN. The "local" option uses a local version of
#' MathJax (which is copied into the output directory). You can pass an
#' alternate URL or pass \code{NULL} to exclude MathJax entirely.
#' @param template Pandoc template to use for rendering. Pass "default"
#' to use the rmarkdown package default template; pass \code{NULL}
#' to use pandoc's built-in template; pass a path to use a custom template
#' that you've created. Note that if you don't use the "default" template
#' then some features of \code{html_document} won't be available (see the
#' Templates section below for more details).
#' @param css One or more css files to include
#' @param includes Named list of additional content to include within the
#' document (typically created using the \code{\link{includes}} function).
#' @param keep_md Keep the markdown file generated by knitting.
#' @param lib_dir Directory to copy dependent HTML libraries (e.g. jquery,
#' bootstrap, etc.) into. By default this will be the name of the document
#' with \code{_files} appended to it.
#' @param pandoc_args Additional command line options to pass to pandoc
#' @param ... Additional function arguments to pass to the base R Markdown HTML
#' output formatter
#'
#' @return R Markdown output format to pass to \code{\link{render}}
#'
#' @details
#'
#' R Markdown documents can have optional metadata that is used to generate a
#' document header that includes the title, author, and date. For more details
#' see the documentation on R Markdown \link[=rmd_metadata]{metadata}.
#'
#' R Markdown documents also support citations. You can find more information on
#' the markdown syntax for citations within the pandoc documentation on
#' \href{http://johnmacfarlane.net/pandoc/demo/example19/Citations.html}{citations}
#' and
#' \href{http://johnmacfarlane.net/pandoc/demo/example19/Footnotes.html}{footnotes}.
#'
#'
#' @section Templates:
#'
#' You can provide a custom HTML template to be used for rendering. The syntax
#' for templates is described in the documentation on
#' \href{http://johnmacfarlane.net/pandoc/demo/example9/templates.html}{pandoc
#' templates}. You can also use the basic pandoc template by passing
#' \code{template = NULL}.
#'
#' Note however that if you choose not to use the "default" HTML template
#' then several aspects of HTML document rendering will behave differently:
#'
#' \itemize{
#' \item{The \code{theme} parameter does not work (you can still
#' provide styles using the \code{css} parameter).
#' }
#' \item{For the \code{highlight} parameter, the default highlighting
#' style will resolve to "pygments" and the "textmate" highlighting
#' style is not available
#' }
#' \item{MathJax will not work if \code{self_contained} is \code{TRUE}
#' (these two options can't be used together in normal pandoc templates).
#' }
#' }
#'
#' Due to the above restrictions, you might consider using the \code{includes}
#' parameter as an alternative to providing a fully custom template.
#'
#' @examples
#' \dontrun{
#'
#' library(rmarkdown)
#'
#' render("input.Rmd", html_document())
#'
#' render("input.Rmd", html_document(toc = TRUE))
#' }
#'
#' @export
html_document <- function(toc = FALSE,
toc_depth = 3,
number_sections = FALSE,
fig_width = 7,
fig_height = 5,
fig_retina = if (!fig_caption) 2,
fig_caption = FALSE,
smart = TRUE,
self_contained = TRUE,
theme = "default",
highlight = "default",
mathjax = "default",
template = "default",
css = NULL,
includes = NULL,
keep_md = FALSE,
lib_dir = NULL,
pandoc_args = NULL,
...) {
# build pandoc args
args <- c("--standalone")
# use section divs
args <- c(args, "--section-divs")
# table of contents
args <- c(args, pandoc_toc_args(toc, toc_depth))
# template path and assets
if (identical(template, "default"))
args <- c(args, "--template",
pandoc_path_arg(rmarkdown_system_file("rmd/h/default.html")))
else if (!is.null(template))
args <- c(args, "--template", pandoc_path_arg(template))
# numbered sections
if (number_sections)
args <- c(args, "--number-sections")
# additional css
for (css_file in css)
args <- c(args, "--css", pandoc_path_arg(css_file))
# pre-processor for arguments that may depend on the name of the
# the input file (e.g. ones that need to copy supporting files)
pre_processor <- function(metadata, input_file, runtime, knit_meta, files_dir,
output_dir) {
# use files_dir as lib_dir if not explicitly specified
if (is.null(lib_dir))
lib_dir <- files_dir
# extra args
args <- c()
# highlight
args <- c(args, pandoc_html_highlight_args(highlight,
template,
self_contained,
lib_dir,
output_dir))
# content includes (we do this here so that user include-in-header content
# goes after dependency generated content). make the paths absolute if
# making a Shiny document so we can resolve them even if rendering
# elsewhere.
args <- c(args, includes_to_pandoc_args(includes,
filter = if (identical(runtime, "shiny"))
normalize_path
else
identity))
# return additional args
args
}
# return format
output_format(
knitr = knitr_options_html(fig_width, fig_height, fig_retina, keep_md),
pandoc = pandoc_options(to = "html",
from = from_rmarkdown(fig_caption),
args = args),
keep_md = keep_md,
clean_supporting = self_contained,
pre_processor = pre_processor,
base_format = html_document_base(smart = smart, theme = theme,
self_contained = self_contained,
lib_dir = lib_dir, mathjax = mathjax,
template = template,
pandoc_args = pandoc_args, ...)
)
}
#' Knitr options for an HTML output format
#'
#' Define knitr options for an R Markdown output format that creates
#' HTML output.
#'
#' @inheritParams html_document
#'
#' @return An list that can be passed as the \code{knitr} argument of the
#' \code{\link{output_format}} function.
#'
#' @seealso \link{knitr_options}, \link{output_format}
#'
#' @export
knitr_options_html <- function(fig_width, fig_height, fig_retina, keep_md) {
opts_chunk <- list(dev = 'png',
dpi = 96,
fig.width = fig_width,
fig.height = fig_height,
fig.retina = fig_retina)
if (keep_md)
opts_chunk$fig.retina <- NULL
knitr_options(opts_chunk = opts_chunk)
}
themes <- function() {
c("default",
"cerulean",
"journal",
"flatly",
"readable",
"spacelab",
"united",
"cosmo")
}
html_highlighters <- function() {
c(highlighters(), "textmate")
}
default_mathjax <- function() {
paste("https://cdn.mathjax.org/mathjax/latest/",
mathjax_config(), sep="")
}
mathjax_config <- function() {
"MathJax.js?config=TeX-AMS-MML_HTMLorMML"
}