The behavior of the default site generation function (rmarkdown::default_site) is described in the article on Creating a Website. It is also possible to define a custom site generator that has alternate behavior.

Site Generator Function

A site generator is an R function that is bound to by including it in the “site:” field of the “index.Rmd” or “” file. For example:


title: "My Book"
output: bookdown::gitbook
site: bookdown::bookdown_site

A site generation function should return a list with the following elements:


The name for the website (e.g. the parent directory name).


The directory where the website output is written to. This path should be relative to the site directory (e.g. “.” or “_site“)


An R function that can be called to generate the site. The function should accept the input_file, output_format, envir, quiet, and encoding arguments.


An R function that returns relative paths to the files generated by render_site (these files are the ones which will be removed by the clean_site function.

Note that the input_file argument will be NULL when the entire site is being generated. It will be set to a specific file name if a front-end tool is attempting to preview it (e.g. RStudio IDE via the Knit button).

When quiet = FALSE the render function should also print a line of output using the message function indicating which output file should be previewed, for example:

if (!quiet)
  message("\nOutput created: ", output)

Emitting this line enables front-ends like RStudio to determine which file they should open to preview the website.


See the source code of the rmarkdown::default_site function for an example of a site generation function.

The bookdown package also implements a custom site generator via it’s bookdown::bookdown_site function.

comments powered by Disqus