5.3 使用 HTTP 服务预览书籍

相比于重复运行 render_book()preview_chapter() 来预览章节,你实际上可以在 web 浏览器中实时预览书籍,你只需要保存 Rmd 文件即可。bookdown 中的函数 serve_book()可以基于 servr 软件包(Xie 2024)启动本地 web 服务器,提供 HTML 输出的在线预览服务。

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

将书籍的根目录传递给 dir 参数,上述函数将启动本地 web 服务器,以便你可以使用服务器查看书籍输出。访问书籍输出页面的默认 URL 是 http://127.0.0.1:4321。如果在交互式 R session 中运行此功能,此 URL 将自动在 web 浏览器中打开。如果你在 RStudio IDE 中,RStudio viewer 将用作默认的 web 浏览器,因此你可以在相同的环境中编写 Rmd 源文件并预览输出(例如,在左侧编写源文件,在右侧查看输出文件)。

服务器将侦听书籍根目录中的更改:每当修改书籍目录中的任何文件,serve_book() 都可以检测到更改,重新编译对应的 Rmd 文件,并自动刷新 web 浏览器。如果修改的文件不包括 Rmd 文件,它只会刷新浏览器(例如只更新了某个 CSS 文件)。这意味着一旦启动了服务器,接下来所要做的就是编写书籍并保存文件。在保存文件时,编译和预览将自动进行。

如果真的不需要太多时间来重新编译整本书,可以设置参数 preview = FALSE,这样每次更新这本书时,整本书都会重新编译,否则只有修改过的章节会通过 preview_chapter() 重新编译。

... 里的参数都会传递给 servr::httw(),请参阅其帮助页面以查看所有可能的选项,例如 daemonport。使用 in_session = TRUEFALSE 有其优缺点:

  • 对于 in_session = TRUE,你可以在当前 R session 中访问在书籍中创建的所有对象;如果使用守护进程(通过参数 daemon = TRUE),你可以在当前 R session 不忙碌时检查对象;否则必须先停止服务器,然后才能检查对象。这当你需要以交互方式探索书中的 R 对象时会很有用。in_session = TRUE 的缺点是输出内容可能与从新的 R session 编译的书不同,因为当前 R session 的状态可能不干净。
  • 对于 in_session = FALSE,你不能从当前 R session 访问书籍中的对象,但其输出内容更有可能是可复制的,因为所有内容都是从新的 R session 中创建的。由于此函数仅用于预览目的,因此 R session 是否干净可能不是一个大问题。

根据具体的用例,你可以选择 in_session = TRUEFALSE。最后,你应该从一个新的 R session 开始运行 render_book() 以生成一个可靠的书籍副本。

参考文献

———. 2024. Servr: A Simple HTTP Server to Serve Static Files or Dynamic Documents. https://github.com/yihui/servr.