Authoring Books and Technical Documents with R Markdown
Description
A open-source (GPL-3) R package to facilitate writing books and long-form articles/reports with R Markdown.
Author(s)
Maintainer: Yihui Xie xie@yihui.name (ORCID)
Other contributors:
Christophe Dervieux cderv@posit.co (ORCID) [contributor]
JJ Allaire [contributor]
Albert Kim [contributor]
Alessandro Samuel-Rosa [contributor]
Andrzej Oles [contributor]
Atsushi Yasumoto (ORCID) [contributor]
Aust Frederik (ORCID) [contributor]
Bastiaan Quast [contributor]
Ben Marwick [contributor]
Chester Ismay [contributor]
Clifton Franklund [contributor]
Daniel Emaasit [contributor]
David Shuman [contributor]
Dean Attali [contributor]
Drew Tyre [contributor]
Ellis Valentiner [contributor]
Frans van Dunne [contributor]
Hadley Wickham [contributor]
Jeff Allen [contributor]
Jennifer Bryan [contributor]
Jonathan McPhers [contributor]
JooYoung Seo (ORCID) [contributor]
Joyce Robbins [contributor]
Junwen Huang [contributor]
Kevin Cheung [contributor]
Kevin Ushey [contributor]
Kim Seonghyun [contributor]
Kirill Muller [contributor]
Luciano Selzer [contributor]
Matthew Lincoln [contributor]
Maximilian Held [contributor]
Michael Sachs [contributor]
Michal Bojanowski [contributor]
Nathan Werth [contributor]
Noam Ross [contributor]
Peter Hickey [contributor]
Pedro Rafael D. Marinho (ORCID) [contributor]
Romain Lesur (ORCID) [contributor]
Sahir Bhatnagar [contributor]
Shir Dekel (ORCID) [contributor]
Steve Simpson [contributor]
Thierry Onkelinx (ORCID) [contributor]
Vincent Fulco [contributor]
Yixuan Qiu [contributor]
Zhuoer Dong [contributor]
Posit Software, PBC [copyright holder, funder]
Bartek Szopka (The jQuery Highlight plugin) [contributor]
Zeno Rocha (clipboard.js library) [copyright holder]
MathQuill contributors (The MathQuill library; authors listed in inst/resources/AUTHORS) [contributor]
FriendCode Inc (The gitbook style, with modifications) [copyright holder, contributor]
See Also
Useful links:
Report bugs at https://github.com/rstudio/bookdown/issues
R Markdown site generator for bookdown
Description
Implementation of custom R Markdown site generator for bookdown.
Usage
bookdown_site(input, ...)
Arguments
input
Website directory (or the name of a file within the directory).
...
Currently unused.
HTML book built with bootstrap4
Description
This output format is built with Bootstrap, using carefully crafted features to provide a clean reading experience whether you are on a phone, tablet, or desktop. To read more about this format, see: https://bookdown.org/yihui/bookdown/html.html#bs4-book
Usage
bs4_book(
theme = bs4_book_theme(),
repo = NULL,
...,
lib_dir = "libs",
pandoc_args = NULL,
extra_dependencies = NULL,
template = "default",
split_bib = FALSE,
footnotes_inline = TRUE
)
bs4_book_theme(primary = "#0068D9", version = 4, ...)
Arguments
theme
A named list or bslib::bs_theme() object.
The default, bs4_book_theme(), resets the base font size to 1rem to
make reading easier and uses a primary colour with greater contrast
against the background.
repo
Either link to repository where book is hosted, used to generate
view source and edit buttons or a list with repository base link, default
branch, subdir and icon
(see "Specifying the repository" in https://bookdown.org/yihui/bookdown/html.html#bootstrap4-style).
template
Pandoc template to use for rendering. Pass "default" to use
the bookdown default template; pass a path to use a custom template. The
default template should be sufficient for most use cases. For advanced user
only, in case you want to develop a custom template, we highly recommend to
start from the default template:
https://github.com/rstudio/bookdown/blob/master/inst/templates/bs4_book.html.
Otherwise, some feature may not work anymore.
footnotes_inline
By default, footnotes will be set inline and shown on
hover. Set to FALSE to keep footnotes at the bottom of the page with
links.
primary
Primary colour: used for links and background of footer.
version
Passed to bslib::bs_theme() . This should not be changed as
bs4_book() has been designed to work with Bootstrap version 4 for now.
Combine different parts of an HTML page
Description
Given the HTML header, body, and footer, etc, build an HTML page.
Usage
build_chapter(
head,
toc,
chapter,
link_prev,
link_next,
rmd_cur,
html_cur,
foot
)
Arguments
head
A character vector of the HTML code before the document title.
toc
A character vector of the table of contents.
chapter
The body of a chapter.
link_prev, link_next
The URL of the previous/next chapter (may be
NULL).
rmd_cur
The Rmd filename of the current chapter (may be NULL).
html_cur
The HTML filename of the current chapter (may be
NULL).
foot
A character vector of the HTML code after the chapter body.
Details
This function is for expert use only. The head and foot
arguments may not be strictly the HTML header and footer. It depends on the
HTML comment tokens in the template (see html_chapters ).
A wrapper function to convert e-books using Calibre
Description
This function calls the command ebook-convert in Calibre
(https://calibre-ebook.com) to convert e-books.
Usage
calibre(input, output, options = "")
Arguments
input
The input filename.
output
The output filename or extension (if only an extension is
provided, the output filename will be the input filename with its extension
replaced by output; for example, calibre('foo.epub', 'mobi')
generates ‘foo.mobi’).
options
A character vector of additional options to be passed to
ebook-convert.
Value
The output filename.
Clean up the output files and directories from the book
Description
After a book is rendered, there will be a series of output files and directories created in the book root directory, typically including ‘*_files/’, ‘*_cache/’, ‘_book/’, and some HTML/LaTeX auxiliary files. These filenames depend on the book configurations. This function identifies these files and directories, and delete them if desired, so you can rebuild the book with a clean source.
Usage
clean_book(clean = getOption("bookdown.clean_book", FALSE))
Arguments
clean
Whether to delete the possible output files. If FALSE,
simply print out a list of files/directories that should probably be
deleted. You can set the global option bookdown.clean_book = TRUE to
force this function to delete files. You are recommended to take a look at
the list of files at least once before actually deleting them, i.e. run
clean_book(FALSE) before clean_book(TRUE).
Create a bookdown project
Description
Create a bookdown project with multiple book output formats, including HTML. Choose one of two HTML book output formats:
Usage
create_gitbook(path)
create_bs4_book(path)
Arguments
path
Absolute path to an empty directory in which to create the bookdown project. In the RStudio IDE, if rstudioapi package available, an RStudio project will be created.
Details
Use
create_gitbook()to usebookdown::gitbook()output formatUse
create_bs4_book()to use abookdown::bs4_book()output format
The function will create a folder with file structure for a bookdown project, and example files with information on how to start.
The EPUB e-book format
Description
Convert a book to the EPUB format, which is is an e-book format supported by many readers, such as Amazon Kindle Fire and iBooks on Apple devices.
Usage
epub_book(
fig_width = 5,
fig_height = 4,
dev = "png",
fig_caption = TRUE,
number_sections = TRUE,
toc = FALSE,
toc_depth = 3,
stylesheet = NULL,
cover_image = NULL,
metadata = NULL,
chapter_level = 1,
epub_version = c("epub3", "epub", "epub2"),
md_extensions = NULL,
global_numbering = !number_sections,
pandoc_args = NULL,
template = "default"
)
Arguments
fig_width, fig_height, dev, fig_caption
Figure options (width, height, the graphical device, and whether to render figure captions).
number_sections
Whether to number sections.
toc, toc_depth
Whether to generate a table of contents, and its depth.
stylesheet
A character vector of paths to CSS stylesheets to be applied to the eBook.
cover_image
The path to a cover image.
metadata
The path to the EPUB metadata file.
chapter_level
The level by which the e-book is split into separate “chapter” files.
epub_version
Whether to use version 3 or 2 of EPUB. This correspond to
Pandoc's supported output format. "epub" is an alias
for "epub3" since Pandoc 2.0 and "epub2" for earlier version.
md_extensions
A character string of Pandoc Markdown extensions.
global_numbering
If TRUE, number figures and tables globally
throughout a document (e.g., Figure 1, Figure 2, ...). If FALSE,
number them sequentially within sections (e.g., Figure 1.1, Figure 1.2,
..., Figure 5.1, Figure 5.2, ...). Note that global_numbering =
FALSE will not work with number_sections = FALSE because sections
are not numbered.
pandoc_args
A vector of additional Pandoc arguments.
template
Pandoc template to use for rendering. Pass "default"
to use Pandoc's built-in template; pass a path to use a custom template.
The default pandoc template should be sufficient for most use cases. In
case you want to develop a custom template, we highly recommend to start
from the default EPUB templates at
https://github.com/jgm/pandoc-templates/.
Note
Figure/table numbers cannot be generated if sections are not numbered
(number_sections = FALSE).
Convert the syntax of theorem and proof environments from code blocks to fenced Divs
Description
This function converts the syntax ‘```{theorem, label, ...}’ to ‘::: {.theorem #label ...}’ (Pandoc's fenced Div) for theorem environments.
Usage
fence_theorems(input, text = xfun::read_utf8(input), output = NULL)
Arguments
input
Path to an Rmd file that contains theorem environments written in the syntax of code blocks.
text
A character vector of the Rmd source. When text is
provided, the input argument will be ignored.
output
The output file to write the converted input content. You can
specify output to be identical to input, which means the
input file will be overwritten. If you want to overwrite the input file,
you are strongly recommended to put the file under version control or make
a backup copy in advance.
Value
If output = NULL, the converted text is returned, otherwise
the text is written to the output file.
References
Learn more about theorems and proofs and custom blocks in the bookdown book.
The GitBook output format
Description
This output format function ported a style provided by GitBook (https://www.gitbook.com) for R Markdown. To read more about this format, see: https://bookdown.org/yihui/bookdown/html.html#gitbook-style
Usage
gitbook(
fig_caption = TRUE,
number_sections = TRUE,
self_contained = FALSE,
anchor_sections = TRUE,
lib_dir = "libs",
global_numbering = !number_sections,
pandoc_args = NULL,
extra_dependencies = list(),
...,
template = "default",
split_by = c("chapter", "section", "0", "1", "2", "3", "4", "5", "6", "chapter+number",
"section+number", "0+number", "1+number", "2+number", "3+number", "4+number",
"5+number", "6+number", "rmd", "none"),
split_bib = TRUE,
config = list(),
table_css = TRUE,
code_folding = c("none", "show", "hide")
)
Arguments
fig_caption, number_sections, self_contained, anchor_sections, lib_dir, pandoc_args, code_folding, extra_dependencies, ...
Arguments to be passed to rmarkdown::html_document()
(... not including toc, and theme).
global_numbering
If TRUE, number figures and tables globally
throughout a document (e.g., Figure 1, Figure 2, ...). If FALSE,
number them sequentially within sections (e.g., Figure 1.1, Figure 1.2,
..., Figure 5.1, Figure 5.2, ...). Note that global_numbering =
FALSE will not work with number_sections = FALSE because sections
are not numbered.
template
Pandoc template to use for rendering. Pass "default"
to use the bookdown default template; pass a path to use a custom template.
The default template should be sufficient for most use cases. In case you
want to develop a custom template, we highly recommend to start from the
default template:
https://github.com/rstudio/bookdown/blob/master/inst/templates/gitbook.html.
split_by
How to name the HTML output files from the book: rmd
uses the base filenames of the input Rmd files to create the HTML
filenames, e.g. generate ‘chapter1.html’ for ‘chapter1.Rmd’;
none or "0" means do not split the HTML file (the book will be
a single HTML file); chapter or "1" means split the file by
the first-level headers; section or "2" means the second-level
headers, "3"-"6" means split the file by the [3-6]-level
headers. For chapter, section and "1"-"6", the
HTML filenames will be determined by the header ID's, e.g. the filename
for the first chapter with a chapter title # Introduction will be
‘introduction.html’; for "chapter+number", "section+number"
and "[1-6]+number" the chapter/section (and higher level section)
numbers will be prepended to the HTML filenames, e.g.
‘1-introduction.html’ and ‘2-1-literature.html’.
split_bib
Whether to split the bibliography onto separate pages where the citations are actually used.
config
A list of configuration options for the gitbook style, such as the font/theme settings.
table_css
TRUE to load gitbook's default CSS for tables. Choose
FALSE to unload and use customized CSS (for example, bootstrap) via
the css option. Default is TRUE.
Build book chapters into separate HTML files
Description
Split the HTML output into chapters while updating relative links (e.g. links
in TOC, footnotes, citations, figure/table cross-references, and so on).
Functions html_book() and tufte_html_book() are simple wrapper
functions of html_chapter() using a specific base output format.
Usage
html_chapters(
toc = TRUE,
number_sections = TRUE,
fig_caption = TRUE,
lib_dir = "libs",
template = bookdown_file("templates/default.html"),
global_numbering = !number_sections,
pandoc_args = NULL,
...,
base_format = rmarkdown::html_document,
split_bib = TRUE,
page_builder = build_chapter,
split_by = c("chapter", "section", "0", "1", "2", "3", "4", "5", "6", "chapter+number",
"section+number", "0+number", "1+number", "2+number", "3+number", "4+number",
"5+number", "6+number", "rmd", "none")
)
html_book(...)
tufte_html_book(...)
Arguments
toc, number_sections, fig_caption, lib_dir, template, pandoc_args
See
rmarkdown::html_document ,
tufte::tufte_html , or the documentation
of the base_format function.
global_numbering
If TRUE, number figures and tables globally
throughout a document (e.g., Figure 1, Figure 2, ...). If FALSE,
number them sequentially within sections (e.g., Figure 1.1, Figure 1.2,
..., Figure 5.1, Figure 5.2, ...). Note that global_numbering =
FALSE will not work with number_sections = FALSE because sections
are not numbered.
...
Other arguments to be passed to base_format. For
html_book() and tufte_html_book(), ... is passed to
html_chapters().
base_format
An output format function to be used as the base format.
split_bib
Whether to split the bibliography onto separate pages where the citations are actually used.
page_builder
A function to combine different parts of a chapter into a
page (an HTML character vector). See build_chapter for the
specification of this function.
split_by
How to name the HTML output files from the book: rmd
uses the base filenames of the input Rmd files to create the HTML
filenames, e.g. generate ‘chapter1.html’ for ‘chapter1.Rmd’;
none or "0" means do not split the HTML file (the book will be
a single HTML file); chapter or "1" means split the file by
the first-level headers; section or "2" means the second-level
headers, "3"-"6" means split the file by the [3-6]-level
headers. For chapter, section and "1"-"6", the
HTML filenames will be determined by the header ID's, e.g. the filename
for the first chapter with a chapter title # Introduction will be
‘introduction.html’; for "chapter+number", "section+number"
and "[1-6]+number" the chapter/section (and higher level section)
numbers will be prepended to the HTML filenames, e.g.
‘1-introduction.html’ and ‘2-1-literature.html’.
Value
An R Markdown output format object to be passed to
bookdown::render_book().
Note
These functions are expected to be used in conjunction with
render_book(). It is almost meaningless if they are used with
rmarkdown::render(). Functions like html_document2 are
designed to work with the latter.
If you want to use a different template, the template must contain three
pairs of HTML comments: ‘<!--bookdown:title:start-->’ and
‘<!--bookdown:title:end-->’ to mark the title section of the book
(this section will be placed only on the first page of the rendered book);
‘<!--bookdown:toc:start-->’ and ‘<!--bookdown:toc:end-->’ to mark
the table of contents section (it will be placed on all chapter pages);
‘<!--bookdown:body:start-->’ and ‘<!--bookdown:body:end-->’ to
mark the HTML body of the book (the HTML body will be split into separate
pages for chapters). You may open the default HTML template
(bookdown:::bookdown_file('templates/default.html')) to see where
these comments were inserted.
Output formats that allow numbering and cross-referencing figures/tables/equations
Description
These are simple wrappers of the output format functions like
rmarkdown::html_document(), and they added the
capability of numbering figures/tables/equations/theorems and
cross-referencing them. See ‘References’ for the syntax. Note you can
also cross-reference sections by their ID's using the same syntax when
sections are numbered. In case you want to enable cross reference in other
formats, use markdown_document2 with base_format argument.
Usage
html_document2(
...,
number_sections = TRUE,
global_numbering = !number_sections,
pandoc_args = NULL,
base_format = rmarkdown::html_document
)
html_fragment2(..., number_sections = FALSE)
html_notebook2(..., number_sections = FALSE)
html_vignette2(..., number_sections = FALSE)
ioslides_presentation2(..., number_sections = FALSE)
slidy_presentation2(..., number_sections = FALSE)
tufte_html2(..., number_sections = FALSE)
pdf_document2(...)
beamer_presentation2(..., number_sections = FALSE)
tufte_handout2(...)
tufte_book2(...)
markdown_document2(
number_sections = TRUE,
fig_caption = TRUE,
md_extensions = NULL,
global_numbering = !number_sections,
pandoc_args = NULL,
...,
base_format = rmarkdown::md_document
)
context_document2(...)
github_document2(...)
odt_document2(...)
powerpoint_presentation2(...)
rtf_document2(...)
word_document2(...)
Arguments
..., fig_caption, md_extensions, pandoc_args
Arguments to be passed to a
specific output format function. For a function foo2(), its
arguments are passed to foo(), e.g. ... of
html_document2() are passed to rmarkdown::html_document().
number_sections
Whether to number section headers: if TRUE,
figure/table numbers will be of the form X.i, where X is the
current first-level section number, and i is an incremental number
(the i-th figure/table); if FALSE, figures/tables will be numbered
sequentially in the document from 1, 2, ..., and you cannot cross-reference
section headers in this case.
global_numbering
If TRUE, number figures and tables globally
throughout a document (e.g., Figure 1, Figure 2, ...). If FALSE,
number them sequentially within sections (e.g., Figure 1.1, Figure 1.2,
..., Figure 5.1, Figure 5.2, ...). Note that global_numbering =
FALSE will not work with number_sections = FALSE because sections
are not numbered.
base_format
An output format function to be used as the base format.
Value
An R Markdown output format object to be passed to
rmarkdown::render().
Note
These output formats are used to generate single output files, such as
a single HTML output file (unlike gitbook, which generates multiple
HTML output files by default).
The functions ‘tufte_*()’ are wrappers of functions in the tufte package.
References
https://bookdown.org/yihui/bookdown/
Convert R Markdown to a PDF book
Description
Convert R Markdown files to PDF after resolving the special tokens of bookdown (e.g., the tokens for references and labels) to native LaTeX commands.
Usage
pdf_book(
toc = TRUE,
number_sections = TRUE,
fig_caption = TRUE,
pandoc_args = NULL,
...,
base_format = rmarkdown::pdf_document,
toc_unnumbered = TRUE,
toc_appendix = FALSE,
toc_bib = FALSE,
quote_footer = NULL,
highlight_bw = FALSE
)
Arguments
toc, number_sections, fig_caption, pandoc_args
See
rmarkdown::pdf_document , or the documentation of
the base_format function.
...
Other arguments to be passed to base_format.
base_format
An output format function to be used as the base format.
toc_unnumbered
Whether to add unnumbered headers to the table of contents.
toc_appendix
Whether to add the appendix to the table of contents.
toc_bib
Whether to add the bibliography section to the table of contents.
quote_footer
If a character vector of length 2 and the quote footer
starts with three dashes (‘---’), quote_footer[1] will be
prepended to the footer, and quote_footer[2] will be appended; if
NULL, the quote footer will not be processed.
highlight_bw
Whether to convert colors for syntax highlighting to black-and-white (grayscale).
Details
This function is based on rmarkdown::pdf_document
(by default) with better default arguments. You can also change the default
format to other LaTeX/PDF format functions using the base_format
argument.
The global R option bookdown.post.latex can be set to a function to
post-process the LaTeX output. This function takes the character vector of
the LaTeX output as its input argument, and should return a character vector
to be written to the ‘.tex’ output file. This gives you full power to
post-process the LaTeX output.
Note
This output format can only be used with render_book().
Publish a book to the web
Description
Publish a book to the web. Note that you should be sure to render all
versions of the book before publishing, unless you have specified
render = TRUE.
Usage
publish_book(
name = NULL,
account = NULL,
server = NULL,
render = c("none", "local", "server")
)
Arguments
name
Name of the book (this will be used in the URL path of the
published book). Defaults to the book_filename in
_bookdown.yml if not specified.
account
Account name to publish to. Will default to any previously
published to account or any single account already associated with
server.
server
Server to publish to (by default beta.rstudioconnect.com but any RStudio Connect server can be published to).
render
Rendering behavior for site:
-
"none"uploads a static version of the current contents of the site directory. -
"local"renders the site locally then uploads it. -
"server"uploads the source of the site to render on the server.
Note that for "none" and "local" source files (e.g. .R, .Rmd and
.md) will not be uploaded to the server.
Render multiple R Markdown documents into a book
Description
Render multiple R Markdown files under the current working directory into a
book. It can be used in the RStudio IDE (specifically, the knit field
in YAML). The preview_chapter() function is a wrapper of
render_book(preview = TRUE).
Usage
render_book(
input = ".",
output_format = NULL,
...,
clean = TRUE,
envir = parent.frame(),
clean_envir = !interactive(),
output_dir = NULL,
new_session = NA,
preview = FALSE,
config_file = "_bookdown.yml"
)
preview_chapter(..., envir = parent.frame())
Arguments
input
A directory, an input filename or multiple filenames. For a
directory, ‘index.Rmd’ will be used if it exists in this (book)
project directory. For filenames, if preview = TRUE, only files
specified in this argument are rendered, otherwise all R Markdown files
specified by the book are rendered.
output_format, ..., clean, envir
Arguments to be passed to
rmarkdown::render(). For preview_chapter(),
... is passed to render_book(). See
rmarkdown::render()
and the
bookdown reference book for details on how output formatting options are
set from YAML or parameters supplied by the user when calling
render_book().
clean_envir
This argument has been deprecated and will be removed in future versions of bookdown.
output_dir
The output directory. If NULL, a field named
output_dir in the configuration file ‘_bookdown.yml’ will be
used (possibly not specified, either, in which case a directory name
‘_book’ will be used).
new_session
Whether to use new R sessions to compile individual Rmd
files (if not provided, the value of the new_session option in
‘_bookdown.yml’ is used; if this is also not provided,
new_session = FALSE).
preview
Whether to render and preview the input files specified by the
input argument. Previewing a certain chapter may save compilation
time as you actively work on this chapter, but the output may not be
accurate (e.g. cross-references to other chapters will not work).
config_file
The book configuration file.
Details
There are two ways to render a book from Rmd files. The default way
(new_session = FALSE) is to merge Rmd files into a single file and
render this file. You can also choose to render each individual Rmd file in a
new R session (new_session = TRUE).
Examples
# see https://bookdown.org/yihui/bookdown for the full documentation
if (file.exists("index.Rmd")) bookdown::render_book("index.Rmd")
## Not run:
# will use the default format defined in index.Rmd or _output.yml
bookdown::render_book("index.Rmd")
# will use the options for format defined in YAML metadata
bookdown::render_book("index.Rmd", "bookdown::pdf_book")
# If you pass an output format object, it must have all the options set
bookdown::render_book("index.Rmd", bookdown::pdf_book(toc = FALSE))
# will render the book in the current directory
bookdown::render_book()
# this is equivalent to
bookdown::render_book("index.Rmd")
# will render the book living in the specified directory
bookdown::render_book("my_book_project")
## End(Not run)
Resolve figure/table/section references in HTML
Description
Post-process the HTML content to resolve references of figures, tables, and
sections, etc. The references are written in the form \@ref(key) in
the R Markdown source document.
Usage
resolve_refs_html(content, global = FALSE)
Arguments
content
A character vector of the HTML content.
global
Whether to number the elements incrementally throughout the
whole document, or number them by the first-level headers. For an R
Markdown output format, global = !number_sections is likely to be a
reasonable default (i.e., when the sections are numbered, you number
figures/tables by sections; otherwise just number them incrementally).
Value
A post-processed character vector of the HTML character.
Examples
library(bookdown)
resolve_refs_html(c("<caption>(#tab:foo) A nice table.</caption>",
"<p>See Table @ref(tab:foo).</p>"), global = TRUE)
Continuously preview the HTML output of a book using the servr package
Description
When any files are modified or added to the book directory, the book will be
automatically recompiled, and the current HTML page in the browser will be
refreshed. This function is based on servr::httw()
to continuously watch a directory.
Usage
serve_book(
dir = ".",
output_dir = "_book",
preview = TRUE,
in_session = TRUE,
quiet = FALSE,
...
)
Arguments
dir
The root directory of the book (containing the Rmd source files).
output_dir
The directory for output files; see
render_book().
preview
Whether to render the modified/added chapters only, or the
whole book; see render_book().
in_session
Whether to compile the book using the current R session, or always open a new R session to compile the book whenever changes occur in the book directory.
quiet
Whether to suppress output (e.g., the knitting progress) in the console.
...
Other arguments passed to servr::httw()
(not including the handler argument, which has been set internally).
Details
For in_session = TRUE, you will have access to all objects created in
the book in the current R session: if you use a daemonized server (via the
argument daemon = TRUE), you can check the objects at any time when
the current R session is not busy; otherwise you will have to stop the server
before you can check the objects. This can be useful when you need to
interactively explore the R objects in the book. The downside of
in_session = TRUE is that the output may be different with the book
compiled from a fresh R session, because the state of the current R session
may not be clean.
For in_session = FALSE, you do not have access to objects in the book
from the current R session, but the output is more likely to be reproducible
since everything is created from new R sessions. Since this function is only
for previewing purposes, the cleanness of the R session may not be a big
concern. You may choose in_session = TRUE or FALSE depending on
your specific applications. Eventually, you should run render_book()
from a fresh R session to generate a reliable copy of the book output.