Skip to contents

This function will serve your lesson and it will auto-update whenever you save a file.


serve(path = ".", quiet = !interactive(), ...)



the path to your lesson. Defaults to the current path.


if TRUE, then no messages are printed to the output. Defaults to FALSE in non-interactive sessions, which allows messages to be printed.


options passed on to servr::server_config() by way of servr::httw(). These can include port and host configuration.


the output of servr::httw(), invisibly. This is mainly used for its side-effect


sandpaper::serve() is an entry point to working on any lesson using The Carpentries Workbench. When you run this function interactively, a preview window will open either in RStudio or your browser with an address like localhost:4321 (note the number will likely be different). When you make changes to files in your lesson, this preview will update automatically.

When you are done with the preview, you can run servr::daemon_stop().

Command line usage

You can use this on the command line if you do not use RStudio or another IDE that acts as a web browser. To run this on the command line, use:

R -e 'sandpaper::serve()'

Note that unlike an interactive session, progress messages are not printed (except for the accessibility checks) and the browser window will not automatically launch. You can have these messages print to screen with the quiet = FALSE argument. In addition, If you want to specify a port and host for this function, you can do so using the port and host arguments:

R -e 'sandpaper::serve(quiet = FALSE, host = "", port = "3435")'

See also

build_lesson(), render the lesson once, locally.


if (FALSE) {
  # create an example lesson
  tmp <- tempfile()
  create_lesson(tmp, open = FALSE)

  # open the episode for editing
  file.edit(fs::path(tmp, "episodes", "01-introduction.Rmd"))

  # serve the lesson and begin editing the file. Watch how the file will
  # auto-update whenever you save it.
  # to stop the server, run
  # If you want to use a different port, you can specify it directly
  sandpaper::serve(host = "", port = "3435")