用 Quarto 将多章节文稿构建为电子书-未完纪

原文：Creating a Book

作者：原页面未标注个人作者

来源：Quarto 文档：Books

Quarto Book 会把多个文档章节组合成一份完整稿件。一个项目可以输出为 HTML、PDF、Microsoft Word、EPUB 或 AsciiDoc。HTML Book 是一种特殊的 Quarto 网站，因此支持网站的功能（例如全文搜索）；与普通网站相比，书籍还使用章节编号，并支持跨章节交叉引用。

Quarto Book 可以发布到 GitHub Pages、Netlify、RStudio Connect，也可以放在其他静态托管服务或内网 Web 服务器上。搭建流程可以分成：创建书籍项目、整理章节、配置输出格式、预览和完整渲染。

创建 Book 项目

Quarto 文档介绍了 Positron、VS Code、RStudio 和终端几种工作方式。

使用 Positron 或 VS Code

在命令面板中执行 Quarto: Create Project，选择 Book Project，再选择父目录并为书籍项目命名。新项目创建并打开后，可以点击 Preview 预览书稿。

使用 RStudio

通过 New Project 新建项目，并选择 Quarto Book。随后填写目录名称以及相关选项，点击 Render 预览书稿。

使用终端

在终端中运行：

quarto create project book mybook

按提示选择项目类型并提供名称；上面的示例会在 mybook 子目录中生成一个简单的书籍项目。然后运行：

quarto preview mybook

预览会在浏览器中打开。编辑并保存 index.qmd 或其他章节文件（例如 intro.qmd）后，预览会自动更新。Positron、VS Code 和 RStudio 的预览界面也会在重新渲染 index.qmd 或其他章节时更新。

安排章节文件

一个简单的书籍项目可以让章节分别保存在 index.qmd、intro.qmd 和 summary.qmd 等文件中。书籍项目目录中的 _quarto.yml 描述书籍配置与章节顺序。

原文给出的配置示例：

project:
  type: book

book:
  title: "mybook"
  author: "Jane Doe"
  date: "8/18/2021"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib
format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
  epub:
    cover-image: cover.png

project.type 将项目类型设为 book。book.chapters 按列表顺序指定书籍内容；示例包含起始页、引言、摘要和参考文献章节。bibliography 指向书目文件。format 下分别指定 HTML 主题、PDF 文档类，以及 EPUB 封面图片路径。这里的 cover.png 只是原文配置示例中的文件名，项目需要提供与配置路径相符的文件。

在配置中填好标题、作者、日期和章节后，后续预览、渲染会基于这份项目设置。若需在书中引用其他章节，Quarto Book 的章节编号和交叉引用功能可以串起跨章节引用。

预览与刷新

在 VS Code 中使用 Preview 按钮，在 RStudio 中使用 Render 按钮，可以在嵌入窗口中渲染和预览。终端也可以在当前项目目录执行：

quarto preview

预览期间，配置文件（例如 _quarto.yml）或书籍资源（例如主题和 CSS）发生变化时，预览会自动刷新。

预览服务器可以通过命令行选项或 _quarto.yml 调整，例如端口、是否打开浏览器等。命令帮助可通过以下命令查看：

quarto preview help

一个重要区别是：局部预览不一定会让所有全局选项都重新作用于每个页面。如果改动了 _quarto.yml 或被包含的文件，应完整重新渲染整本书。正式部署前，始终运行 quarto render，即使预览服务器已经更新了部分章节。

完整渲染与输出目录

准备发布书籍时，在项目根目录运行：

quarto render

不指定格式时，Quarto 会渲染所有配置的输出格式。若只需要某一种格式，可以使用 --to 参数，例如：

quarto render           # 渲染所有格式
quarto render --to pdf  # 只生成 PDF

输出默认写入书籍项目的 _book 子目录。例如：

mybook/
  _book/
    index.html
    mybook.pdf
    mybook.epub

具体会生成哪些文件取决于项目配置中启用的格式。部署书籍时，Quarto 文档将网站发布作为进一步参考；书籍使用的输出目录应是 _book，而不是普通网站文档里常见的 _site。

预览 AsciiDoc 书籍

对于 AsciiDoc Book，Quarto 建议在创作期间先使用内置 HTML 格式预览，这样可以继续利用 Quarto 的预览流程。接近交付时，再用 Asciidoctor 工具链编译成 PDF 或 HTML，以检查最终格式。

生成 PDF 预览前，需要依照 Asciidoctor PDF 的安装说明准备工具。之后在项目根目录运行：

asciidoctor-pdf _book/book-asciidoc/<title>.adoc

PDF 会写入：

_book/book-asciidoc/<title>.pdf

如果要生成 HTML 预览，先按 Asciidoctor 安装说明准备工具，然后运行：

asciidoctor _book/book-asciidoc/<title>.adoc

工具会生成包含整本书内容的单个 HTML 文件：

_book/book-asciidoc/<title>.html

该 HTML 仍会引用 _book/book-asciidoc/ 目录中的资源和图片。若单独移动 HTML 文件而不带上这些资源目录，图片等内容就可能无法显示。

继续扩展书籍

Quarto Books 文档还列出了几类后续主题：Book Structure 介绍章节编号与未编号标题、分部和附录；Book Crossrefs 说明如何引用章节、图、表和公式；Book Output 讨论各种格式的外观、导航和读者工具；Book Options 汇总可用选项。文档也指向大型书籍或计算成本高时的渲染优化，以及将书籍网站发布到不同托管服务的说明。

来源与作者信息：Quarto 文档“Books”中的“Creating a Book”页面；原页面未标注个人作者。原文链接：https://quarto.org/docs/books