5.3 Serve the book

Instead of running render_book() or preview_chapter() over and over again, you can actually live preview the book in the web browser, and the only thing you need to do is save the Rmd file. The function serve_book() in bookdown can start a local web server to serve the HTML output based on the servr package (Xie 2020c).

serve_book(dir = ".", output_dir = "_book",
  preview = TRUE, in_session = TRUE, quiet = FALSE,
  ...)

You pass the root directory of the book to the dir argument, and this function will start a local web server so you can view the book output using the server. The default URL to access the book output is http://127.0.0.1:4321. If you run this function in an interactive R session, this URL will be automatically opened in your web browser. If you are in the RStudio IDE, the RStudio Viewer will be used as the default web browser, so you will be able to write the Rmd source files and preview the output in the same environment (e.g., source on the left and output on the right).

The server will listen to changes in the book root directory: whenever you modify any files in the book directory, serve_book() can detect the changes, recompile the Rmd files, and refresh the web browser automatically. If the modified files do not include Rmd files, it just refreshes the browser (e.g., if you only updated a certain CSS file). This means once the server is launched, all you have to do next is simply write the book and save the files. Compilation and preview will take place automatically as you save files.

If it does not really take too much time to recompile the whole book, you may set the argument preview = FALSE, so that every time you update the book, the whole book is recompiled, otherwise only the modified chapters are recompiled via preview_chapter().

The arguments in ... are passed to servr::httw(), and please refer to its help page to see all possible options, such as daemon and port. There are pros and cons of using in_session = TRUE or FALSE:

  • 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 use cases. Eventually, you should run render_book() from a fresh R session to generate a reliable copy of the book output.

References

Xie, Yihui. 2020c. Servr: A Simple Http Server to Serve Static Files or Dynamic Documents. https://github.com/yihui/servr.