5.3 使用 HTTP 服务预览书籍
相比于重复运行 render_book()
或 preview_chapter()
来预览章节,你实际上可以在 web 浏览器中实时预览书籍,你只需要保存 Rmd 文件即可。bookdown 中的函数 serve_book()
可以基于 servr 软件包(Xie 2024)启动本地 web 服务器,提供 HTML 输出的在线预览服务。
将书籍的根目录传递给 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()
,请参阅其帮助页面以查看所有可能的选项,例如 daemon
和 port
。使用 in_session = TRUE
或 FALSE
有其优缺点:
- 对于
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 = TRUE
或 FALSE
。最后,你应该从一个新的 R session 开始运行 render_book()
以生成一个可靠的书籍副本。