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 “index.md” file. For example:

index.Rmd

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

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

name

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

output_dir

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

render

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.

clean

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.

Examples

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