5.3 Serve the book
Instead of running
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 2017c).
serve_book(dir = ".", output_dir = "_book", preview = TRUE, in_session = TRUE, ...)
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
The arguments in
... are passed to
servr::httw(), and please refer to its help page to see all possible options, such as
port. There are pros and cons of using
in_session = TRUE or
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 = TRUEis 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.
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.
Xie, Yihui. 2017c. Servr: A Simple Http Server to Serve Static Files or Dynamic Documents. https://CRAN.R-project.org/package=servr.